Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Plugins
Ein Plugin ist ein separates Programm oder ein Dienst, den du betreibst und dem der Server über das Netzwerk eine eng umrissene Aufgabe übergibt. Der Server verbindet sich nur mit einer Adresse: Er startet, stoppt oder überwacht das Plugin nicht. Betreibe es als Sidecar, unter systemd oder auf einer anderen Maschine.
Standardmäßig wird nichts delegiert. Ein Server ohne Plugin-Adresse öffnet keine Verbindung und startet keinen Prozess.
Vom oberen Rand des Diagramms nach unten:
- Der my-Prozess, mit beliebiger
role, macht zwei Arten von Aufrufen an ein Plugin.- Ports, die er übergibt: Ein Plugin erledigt eine Aufgabe anstelle eines eingebauten Teils, und jeder ist nur eingeschaltet, wenn eine Einstellung
pluginnennt:translator(die Servereinstellungtranslation_providers = plugin),billing(billing_sourcesenthältplugin),mailer(mail = plugin),media_image,media_videoundmedia_audio(media_image = pluginund so weiter),key_manager(key_manager = plugin) undsearch(search = plugin). - Entscheidungs-Hooks: Ein Plugin antwortet, ob etwas angenommen werden soll, und wird gefragt, solange der Modus
hook_<hook>_modedes Hooks nichtoffist:inbound.statusfür Beiträge von anderen Servern,inbound.followfür Follows von anderen Servern,signup.checkfür Registrierungen,media.checkfür Uploads,local.statusfür Beiträge lokaler Konten,inbound.actorfür die Profile von Konten auf anderen Servern undlocal.profilefür Profiländerungen lokaler Konten.
- Ports, die er übergibt: Ein Plugin erledigt eine Aufgabe anstelle eines eingebauten Teils, und jeder ist nur eingeschaltet, wenn eine Einstellung
- Der Plugin-Client macht jeden Aufruf. Jede Art hat ein Ziel,
plugin_<kind>_address, und eine Deadline,plugin_<kind>_timeout, und führt höchstens 8 Aufrufe gleichzeitig aus (2 für jede Medienart). Er verbindet sich über einen Unix-Socket,https://oder, nur für einige Arten,http://. - Deine Plugins sind separate Programme, die du betreibst, als Sidecar, unter systemd oder auf einer anderen Maschine. Der Server verbindet sich nur mit ihnen.
- Wenn ein Aufruf fehlschlägt oder abläuft (Details):
billing,mailerund die Medienarten: Der Job, der den Aufruf gemacht hat, läuft später erneut.translator: Der Server fragt den nächsten Anbieter, und wenn keiner übrig ist, sieht der Leser, dass die Übersetzung fehlgeschlagen ist.key_managerschlägt geschlossen fehl: Alles, was einen Schlüssel braucht, schlägt fehl, und der Server startet nicht ohne das Plugin.search: Der Job eines Schreibvorgangs läuft später erneut, und eine Suche schlägt fehl, sodass die Person sieht, dass die Suche nicht verfügbar ist.- Ein Entscheidungs-Hook tut, was
hook_<hook>_on_failuresagt:pass,retryoder, bei Registrierungen,require_approval.
Jede Art hat ihr eigenes Ziel, unter den Einstellungen plugin_<kind>_*. Ein Punkt im Namen einer Art wird im
Schlüssel zu _, sodass inbound.status plugin_inbound_status_address hat.
| Art | Was sie trägt | Einfaches TCP (http://) |
Standardprotokoll | Standard-Deadline |
|---|---|---|---|---|
translator |
Den Text eines Beitrags, den ein Leser übersetzen lassen wollte | Abgelehnt | json |
10 s |
search |
Text, Autor, Sichtbarkeit und Sprache von public- und local-Beiträgen sowie die Suchanfragen angemeldeter Personen |
Abgelehnt | json |
10 s |
billing |
Die Kosten des Servers | Erlaubt | json |
2 min |
mailer |
Adressen und Secrets wie Bestätigungslinks | Abgelehnt | json |
30 s |
media_image |
Hochgeladene Bilder mit ihren Metadaten, die einen Standort enthalten können | Erlaubt | proto |
4 min |
media_video |
Hochgeladene Videos mit ihren Metadaten, die einen Standort enthalten können | Erlaubt | proto |
4 min |
media_audio |
Hochgeladene Audiodateien mit ihren Metadaten | Erlaubt | proto |
4 min |
key_manager |
Datenverschlüsselungsschlüssel im Klartext | Abgelehnt | json |
5 s |
inbound.status |
Den Text eingehender Beiträge | Abgelehnt | json |
3 s |
local.status |
Den Text lokaler Beiträge | Abgelehnt | json |
1 s |
local.profile |
Das öffentliche Profil lokaler Konten, ohne Bilder | Erlaubt | json |
1 s |
inbound.follow |
Die beiden Seiten eines Follows | Erlaubt | json |
3 s |
inbound.actor |
Die öffentlichen Profile von Konten auf anderen Servern | Erlaubt | json |
3 s |
signup.check |
E-Mail-Adressen und IP-Adressen | Abgelehnt | json |
2 s |
media.check |
Eine kleine verarbeitete Version des Mediums, nie das Original | Erlaubt | json |
10 s |
Die Einstellungen, die den Server ein Ziel nutzen lassen, gehören zur jeweiligen Funktion: Die letzten fünf Arten der Tabelle sind die Entscheidungs-Hooks. Diese Seite behandelt, was sie gemeinsam haben.
Der Server sendet pro Nachricht höchstens das feste Limit einer Art und liest höchstens ein anderes. Ein Aufruf über dem Limit schlägt fehl, und der Job, der ihn gemacht hat, versucht es erneut.
Das Ziel
Abschnitt betitelt „Das Ziel“Die Einstellungen gibt es nur in der Konfigurationsdatei und der Umgebung (Konfigurationsreferenz). Keine Servereinstellung, Admin-Seite oder API kann sie anzeigen oder ändern, sodass ein gestohlenes Administratorkonto weder Beiträge noch Schlüssel umleiten kann. Eine Änderung wirkt nach einem Neustart.
plugin_<kind>_address hat eine von drei Formen. Der Server prüft die Form beim Start, ohne den Namen aufzulösen, und
löst den Namen bei jeder Verbindung auf.
unix:///run/my/mailer.sock: ein Unix-Socket.https://mailer.internal:8443: TLS über TCP. Der Server verifiziert das Zertifikat immer, gegenplugin_<kind>_tls_ca_fileoder die Wurzeln des Systems, und keine Einstellung schaltet das ab.http://billing.internal:5000: einfaches TCP.
Authentifizierung
Abschnitt betitelt „Authentifizierung“Wähle eine:
- Ein Unix-Socket: Die Berechtigungen der Datei des Sockets schützen ihn.
- mTLS:
plugin_<kind>_tls_cert_fileundplugin_<kind>_tls_key_file, mit einerhttps://-Adresse. - Ein Bearer-Token:
plugin_<kind>_token(oderMY_PLUGIN_<KIND>_TOKEN_FILE), gesendet alsAuthorization: Bearer, nur überhttps://oder einen Unix-Socket. Ein Token mit einerhttp://-Adresse ist ein Konfigurationsfehler.
Eine https://-Adresse ohne Token und ohne Client-Zertifikat startet mit einer Warnung, da das Plugin den Server nicht von
jedem anderen unterscheiden kann, der es erreicht.
Der Server liest die Dateien von plugin_<kind>_tls_ca_file, plugin_<kind>_tls_cert_file und
plugin_<kind>_tls_key_file beim Start, wobei eine fehlende oder unlesbare Datei ihn stoppt. Danach prüft er sie höchstens alle 5 Sekunden
auf Änderungen, wenn er eine neue Verbindung öffnet, sodass ein kurzlebiges Zertifikat oder eine CA, die ein
Zertifikatsmanager wie Vault, cert-manager oder SPIFFE an Ort und Stelle erneuert, ohne Neustart funktioniert. Bereits
offene Verbindungen behalten das Zertifikat, mit dem sie begonnen haben, bis sie schließen. Solange eine Erneuerung halb geschrieben ist, etwa ein neues
Zertifikat, dessen Schlüssel noch nicht bereitliegt, behält der Server die zuletzt gelesenen Dateien und versucht es bei der nächsten
Verbindung erneut. Das Token wird nur beim Start gelesen.
Einfaches TCP
Abschnitt betitelt „Einfaches TCP“mailer, key_manager, translator, search, inbound.status, local.status und signup.check lehnen http:// ab: Der Server startet nicht. Das gilt auch auf
Loopback (http://127.0.0.1), da eine Loopback-Adresse andere Prozesse auf dem Host nicht daran hindert, den
Datenverkehr zu lesen. Lege einen solchen Sidecar auf einen Unix-Socket in einem gemeinsamen Volume.
Die anderen Arten akzeptieren http://, und der Server loggt beim Start eine Warnung, die die Art und die Adresse nennt. Nichts
verschlüsselt oder authentifiziert diesen Datenverkehr, und es kann kein Bearer-Token darüber verwendet werden. Dieses Netzwerk
geschlossen zu halten, liegt in deiner Verantwortung: Was die Tabelle oben aufführt, überquert es im Klartext.
Protokolle
Abschnitt betitelt „Protokolle“plugin_<kind>_protocol sagt, was der Server sendet, und es muss das sein, was das Plugin akzeptiert.
| Wert | Der Server sendet | Für |
|---|---|---|
json |
Das Unary-Protokoll von Connect mit application/json, über HTTP/1.1 auf einfachen Verbindungen |
Ein Plugin, das auf einer Connect-Bibliothek oder allein auf einem HTTP-Server und einer JSON-Bibliothek aufbaut |
proto |
Das Protokoll von Connect mit application/proto |
Ein Plugin, das auf einer Connect-Bibliothek aufbaut |
grpc |
gRPC über HTTP/2 | Ein Plugin, das nur gRPC spricht |
Ein Plugin beantwortet das falsche Protokoll mit 415. Die Medienarten streamen in beide Richtungen, was HTTP/2 braucht, daher nehmen sie proto
oder grpc, und json ist ein Konfigurationsfehler.
Die Definitionen des Protokolls sind die .proto-Dateien unter api/plugin/ des Repositorys. Es gibt ein Paket für jede
Art von Port, und sie teilen keine Typen; die Entscheidungs-Hooks teilen sich alle ein Paket, my.plugin.hook.v1.
Das Plugin-Protokoll enthält die aus diesen Dateien erzeugte Referenz jedes Pakets.
Wenn ein Aufruf fehlschlägt
Abschnitt betitelt „Wenn ein Aufruf fehlschlägt“Ein Aufruf wartet auf seinen Platz unter den gleichzeitig laufenden Aufrufen seiner Art, und die Wartezeit zählt für seine Deadline und für die
Metrik my.plugin.slot_wait. Ein fehlgeschlagener Aufruf zählt in der Metrik my.plugin.failures nach Art und Connect-Code. Der Server verwirft die
Nachricht, die ein Plugin in einen Fehler legt, sodass die Gründe für die Fehler eines Plugins im eigenen Log des Plugins stehen. Der Server
wiederholt einen Aufruf nicht selbst: Das tut der Job, der ihn gemacht hat, ein Plugin muss also mit demselben Aufruf zweimal zurechtkommen.
Ein Plugin, das beim Start des Servers ausgefallen ist, stoppt nichts, außer key_manager: Der Server startet nicht ohne es, und
was ohne es stoppt ist ein Teil seiner Einrichtung, den man zuerst lesen sollte.
Ein Aufruf hat die Deadline von plugin_<kind>_timeout, und ein Plugin erhält sie als Connect-Timeout-Ms (grpc-timeout bei
gRPC). Ein Plugin darf diesen Header ignorieren: Der Server hört ohnehin auf zu warten. Die Deadline muss für die
Arten, auf die eine Anfrage warten kann (key_manager, translator, search, signup.check, media.check, local.status, inbound.actor und local.profile), unter 30 Sekunden bleiben und
für die anderen unter 5 Minuten, so lange ein Job höchstens laufen darf.
Ein Plugin testen
Abschnitt betitelt „Ein Plugin testen“my plugin test führt den Vertrag einer Art gegen ein laufendes Plugin aus und meldet jeden Fall. Es liest keine Konfiguration,
alles, was es braucht, ist also die Binärdatei 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 skippedDer Exit-Code ist 1, wenn ein Fall fehlschlägt. Die Flags bedeuten das, was die Einstellungen bedeuten: --protocol, --token-file, --tls-ca-file,
--tls-cert-file, --tls-key-file und --timeout. Es wendet dieselben Regeln an wie der Server, sodass --kind mailer eine
http://-Adresse ablehnt. Das getestete Plugin kann ein echtes sein, daher läuft ein Fall, der mehr tut als den Aufruf selbst, nur, wenn
ein Flag ihn verlangt. Eine Art, deren Vertrag die Version noch nicht hat, meldet reachable und ein SKIP.
--kind billing prüft nur, dass das Plugin sich weigert, etwas auszugeben, wenn keine abgerechnete Anfrage erlaubt ist. --billed macht außerdem
einen echten Abruf des laufenden und des vorherigen Monats und prüft die Antwort wie ein Import; das kann bei den Anbietern hinter dem Plugin
Geld kosten. Cloud-Nutzungskosten importieren enthält den
Vertrag der Art.
--kind mailer macht keinen Aufruf des RPC, es sei denn, --mail-to nennt einen Empfänger. Damit sendet der Befehl eine echte Nachricht dorthin,
von --mail-from (Standard: dieselbe Adresse), und prüft, dass das Plugin eine Anfrage ohne Empfänger ablehnt.
E-Mails senden enthält den Vertrag der Art.
--kind translator sendet ein paar feste englische Sätze und übersetzt sie ins Japanische (--translate-from und --translate-to
wählen ein anderes Paar für ein Plugin, das nur einige hat). Ein Dienst hinter dem Plugin, der pro Zeichen abrechnet, rechnet auch diese ab,
etwa 200 Zeichen. Es prüft die Form der Antworten und dass das Plugin die Sprache qaa ablehnt, einen Code, den ISO 639
für den privaten Gebrauch freilässt. Es kann die Wörter nicht beurteilen, lies also eine Übersetzung des Plugins selbst.
Beiträge übersetzen enthält den Vertrag der Art.
--kind search sucht und schreibt und entfernt nur eigene Dokumente: einige mit IDs, die kein Beitrag hat, von einem
Autor, der kein Konto ist, mit einem für den Lauf erfundenen Wort, die es am Ende entfernt. Es prüft, dass eine Suchanfrage ohne
Wort nichts findet, dass eine Suchanfrage in der Abfragesprache einer Engine oder auf Japanisch nicht fehlschlägt, dass das Plugin einen
Cursor ablehnt, den es nicht ausgegeben hat, und dass Dokumente die neuesten zuerst, seitenweise, ersetzt und nach Beitrag und nach
Autor entfernt gefunden werden. --clear-index führt außerdem die Fälle aus, die jedes Dokument einer Sichtbarkeit und den ganzen Index entfernen: Nutze es nur
gegen einen Index zum Testen. Beiträge durchsuchen enthält den Vertrag der Art.
--kind media_image, --kind media_video und --kind media_audio senden nur kleine Testdateien, die sie selbst erzeugen:
ein Foto, ein Emoji und ein animiertes GIF, ein MP4 mit Video und Tonspur oder ein MP3. Jede versteckt einen Standort oder einen
Titel in ihren Metadaten, und ein Fall schlägt fehl, wenn das in einer Ausgabe zurückkommt. Sie prüfen jede Ausgabe wie der Server.
Medien konvertieren enthält den Vertrag der Arten.
--kind key_manager führt die Prüfungen aus, die der Server bei jedem Start ausführt, und prüft, dass das Plugin einen geänderten Wert und einen
KEK ablehnt, den es nicht hält. Es sendet nur Schlüssel, die es sich ausdenkt und wegwirft, ist also sicher gegen einen echten Schlüsselspeicher, der
die Aufrufe abrechnen kann. Es prüft, dass die Antworten die richtige Form haben, nicht, wie das Plugin seinen KEK aufbewahrt.
Den Schlüssel verwalten enthält den Vertrag der Art.
probe ist die kleinste Art, und der Server delegiert nichts an sie. Stelle sie zuerst bereit, um den Transport, das
Protokoll und die Authentifizierung zu prüfen, bevor du den Rest des Plugins schreibst.
Beiträge übersetzen
Abschnitt betitelt „Beiträge übersetzen“Ein Plugin der Art translator lässt den Server einen Beitrag übersetzen, wenn ein Leser darum bittet, über einen Dienst deiner Wahl
außer den eingebauten Anbietern (LibreTranslate, DeepL, Google Cloud Translation und Amazon
Translate). Ohne serverseitigen Anbieter ist die einzige Übersetzung die im Browser des Lesers eingebaute, die es
nur in Desktop-Chrome, Edge und Opera gibt: Leser auf einem Handy, in Firefox oder in Safari erhalten keine Übersetzen-Schaltfläche, bis du
einen aktivierst.
MY_PLUGIN_TRANSLATOR_ADDRESS=unix:///run/my/translator.sockMY_PLUGIN_TRANSLATOR_NAME="Our translator" # what readers see next to a translation- Setze
plugin_translator_addressundplugin_translator_nameund starte neu. Der Name ist erforderlich, da Leser einer Übersetzung je nach ihrer Herkunft vertrauen. Die Adresse verlässt die Konfiguration nie. - Aktualisiere deine Datenschutzerklärung und nenne den Dienst hinter dem Plugin als Übersetzungsdienst: Was das Plugin weitergibt, ist das, was es erhält.
- Aktiviere es mit der Servereinstellung
translation_providers = plugin. Eine Änderung wirkt sofort.
Eine Adresse zu haben aktiviert nichts: Solange die Einstellung nicht plugin nennt, sendet der Server nichts und Leser sehen keine Schaltfläche.
Das Plugin ist ein Anbieter wie jeder andere. translation_provider_visibilities bestimmt, was es
erhalten darf, die monatlichen Limits zählen, was ihm gesendet wird, und eine von ihm erstellte Übersetzung bleibt wie jede andere im Cache des Servers.
Ist translation_reports_to_server eingeschaltet, erhält es auch, was Moderatoren in einer Meldung übersetzen lassen, nach denselben Sichtbarkeiten.
Es kann in der Reihenfolge von translation_providers vor oder nach einem anderen Anbieter stehen.
Was das Plugin erhält
Abschnitt betitelt „Was das Plugin erhält“Das Plugin erhält den Text eines Beitrags, wenn ein Leser um eine Übersetzung bittet: seinen Text, die Inhaltswarnung, Umfrageoptionen und Bildbeschreibungen sowie die Sprache des Textes und die Sprache, in die übersetzt werden soll. Es erhält nicht die Adresse des Beitrags, seinen Autor, den Leser, Erwähnungen, Hashtags, Links, eigene Emojis oder Code: Nummerierte Markierungen stehen für sie.
Standardmäßig sind das public-, local- und unlisted-Beiträge. private- und direct-Beiträge erreichen das Plugin nur, wenn du sie
erlaubst, mit translation_provider_visibilities = plugin=public|local|unlisted|private|direct. Dann liest das Plugin, und jeder
Dienst dahinter, Text, den der Autor für wenige Menschen gemeint hat; erlaube sie also nur, wenn du kontrollierst, wohin der Text geht,
und sage das in deiner Datenschutzerklärung. Der Server kann Text, den er gesendet hat, nicht zurückrufen.
Der Server lehnt für diese Art http:// ab, auch auf Loopback, weil der Text der Text von Beiträgen ist. Verwende einen Unix-Socket oder
https://.
Ein LLM hinter einem Plugin
Abschnitt betitelt „Ein LLM hinter einem Plugin“Der Server hat keinen LLM-Anbieter und bietet absichtlich keinen an. Jeder kann einen Beitrag schreiben, daher ist der zu übersetzende Text ein Weg, einem LLM Anweisungen zu geben (eine Prompt Injection), und Leser halten eine Übersetzung für das, was der Beitrag sagt. Sanitizing schützt das HTML einer Seite: Es kann nicht verhindern, dass eine Übersetzung etwas sagt, das der Beitrag nicht sagt.
Der Server kann nicht sehen, was ein Plugin aufruft. Wenn dein Plugin ein LLM verwendet, liegen dieses Risiko und seine Folgen in deiner eigenen Verantwortung.
Der Vertrag
Abschnitt betitelt „Der Vertrag“Der RPC ist Translate von 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"}sourceLanguageist ein BCP-47-Tag oderund, wenn der Server die Sprache nicht kennt. Das Plugin erkennt sie dann und meldet sie indetectedLanguageoder antwortet mitOUTCOME_UNSUPPORTED_LANGUAGE.detectedLanguagedarf fehlen, wenn das Plugin nichts hinzuzufügen hat, und der Server ignoriert einen Wert, der kein Sprach-Tag ist.translationshat einen Eintrag pro Fragment, in der Reihenfolge der Fragmente, keiner davon leer. Ein Fragment kann aus nichts als Markierungen bestehen, und seine Übersetzung sind dann diese Markierungen.⟦1⟧steht für ein Element oder öffnet ein Paar, das⟦/1⟧schließt. Jede Markierung eines Fragments kommt genau einmal in seiner Übersetzung zurück, unverändert. Elemente dürfen sich verschieben, wie es die Wortstellung verlangt, aber ein Paar bleibt offen, bevor es schließt, und Paare verschachteln sich.- Eine Übersetzung ist einfacher Text. Der Server maskiert jedes Markup darin und bereinigt das Ergebnis, bevor er es speichert oder anzeigt.
outcome |
Bedeutung | Was der Server tut |
|---|---|---|
OUTCOME_OK |
Die Übersetzungen stehen in der Antwort | Prüft sie, speichert sie und antwortet dem Leser |
OUTCOME_TEMPORARY |
Der Dienst ist ausgefallen oder hat nicht geantwortet | Versucht den nächsten Anbieter |
OUTCOME_PROVIDER_LIMIT |
Der Dienst meldet sein eigenes Ratenlimit oder Kontingent | Versucht den nächsten Anbieter |
OUTCOME_UNSUPPORTED_LANGUAGE |
Der Dienst hat die Quell- oder Zielsprache nicht oder kann sie nicht erkennen | Versucht den nächsten Anbieter und sagt es dem Leser, wenn keiner sie hat |
Eine Antwort, die diese Regeln verletzt, zählt als OUTCOME_TEMPORARY, und nichts davon wird gespeichert, wie bei einem fehlenden oder unbekannten
outcome und einem fehlgeschlagenen Aufruf. Antwortet kein Anbieter, sieht der Leser, dass die Übersetzung fehlgeschlagen ist, und der Beitrag bleibt, wie er ist, es sei denn,
translation_browser ist eingeschaltet und der Browser des Lesers kann den Beitrag übersetzen: Der Web-Client übersetzt ihn dann dort.
Die Zeichen jedes Aufrufs zählen für die monatlichen Limits, auch bei einem Aufruf, der fehlschlägt, da der Dienst sie erhalten haben kann.
Der Server hört nach plugin_translator_timeout auf zu warten und nach 20 Sekunden, was auch immer diese Einstellung sagt. Alle
Anbieter einer Anfrage erhalten zusammen 45 Sekunden. Er wiederholt einen
fehlgeschlagenen Aufruf nicht, und dieselben Fragmente können für einen anderen Leser erneut kommen.
Beiträge durchsuchen
Abschnitt betitelt „Beiträge durchsuchen“Ein Plugin der Art search pflegt den Index der Volltextsuche für Beiträge in einer Engine, für die der Server
keine eingebaute Unterstützung hat, etwa Groonga oder PGroonga, einen mit Sudachi gebauten Index, Typesense, Manticore oder einen gehosteten
Suchdienst. Für den Server ist es eine weitere Engine: Dieselben Beiträge kommen in den Index, dieselben Jobs halten ihn aktuell,
und der Server entscheidet weiterhin, was jede Person sehen darf.
MY_SEARCH=pluginMY_PLUGIN_SEARCH_ADDRESS=unix:///run/my/search.sock- Starte das Plugin und prüfe es mit
my plugin test --kind search. - Setze
search = pluginundplugin_search_addressund folge Einschalten, wie bei jeder Engine: Der Index füllt sich von da an, undmy search rebuildfügt die vorhandenen Beiträge hinzu. - Wenn das Plugin die Beiträge an einen Dienst eines anderen Unternehmens schickt, nenne diesen Dienst in deinen Datenschutzdokumenten.
Der Server öffnet beim Start keine Verbindung, ein ausgefallenes Plugin stoppt also nichts außer der Suche. Um zum Plugin oder von ihm weg zu wechseln, folge Die Engine abschalten oder wechseln.
Was das Plugin erhält
Abschnitt betitelt „Was das Plugin erhält“- Die Beiträge des Index. Für jeden Beitrag, den der Index enthält, erhält das Plugin seinen Text (den Text, die Inhalts-
warnung und die Bildbeschreibungen, als einfachen Text), seine ID, die Konto-ID seines Autors, seine Sichtbarkeit, seine Sprache
und wann er veröffentlicht wurde. Das sind nur
public- undlocal-Beiträge, wiesearch_visibilitieses sagt, von Autoren, die die Suche erlauben.local-Beiträge sind allein für die Konten dieses Servers gedacht: Das Plugin und jeder Dienst dahinter liest sie ebenfalls.unlisted-,private- unddirect-Beiträge erreichen es nie. - Die Suchanfragen. Wenn eine angemeldete Person Beiträge durchsucht, erhält das Plugin, was sie getippt hat, mit dem Cursor der Seite und der Zahl der Ergebnisse. Es erhält nicht, wer gesucht hat.
- Die Entfernungen: eines Beitrags, aller Beiträge eines Kontos, aller Beiträge einer Sichtbarkeit und des ganzen Index.
Das Plugin gibt nur Beitrags-IDs zurück. Der Server liest jeden Beitrag erneut aus seiner Datenbank und zeigt nur, was die Person jetzt sehen darf, sodass ein Plugin keinem einen Beitrag zeigen kann, der ihn nicht sehen darf, und ein Index, der hinterherhinkt, nur weniger findet. Der Server zeigt die Fehler eines Plugins außerdem niemandem.
Der Server lehnt für diese Art http:// ab, auch auf Loopback, weil sie den Text von Beiträgen trägt und das, wonach Menschen
suchen. Verwende einen Unix-Socket oder https://.
Der Vertrag
Abschnitt betitelt „Der Vertrag“Der Dienst ist my.plugin.search.v1.SearchService, mit einem RPC pro Operation:
| RPC | Was er tut |
|---|---|
Replace |
Fügt das Dokument eines Beitrags hinzu oder ersetzt das Dokument mit derselben statusId |
Remove |
Entfernt das Dokument eines Beitrags |
RemoveByAuthor |
Entfernt jedes Dokument eines Kontos |
RemoveByVisibility |
Entfernt jedes Dokument einer Sichtbarkeit, VISIBILITY_PUBLIC oder VISIBILITY_LOCAL |
Clear |
Entfernt jedes Dokument; der Index nimmt danach wieder Dokumente auf |
Search |
Gibt eine Seite der IDs der Dokumente zurück, die eine Suchanfrage findet, die neuesten zuerst |
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"}- Eine Suchanfrage ist einfacher Text. Das Plugin zerlegt sie in Wörter und findet die Dokumente mit jedem Wort. Es liest den Text nie als Abfragesprache seiner Engine: Ein Operator, ein Platzhalter, ein Anführungszeichen oder ein Feldname darin ist nur Text. Eine Suchanfrage ohne Wort findet nichts. Wie das Plugin Wörter auf Japanisch und in anderen Sprachen findet, die ohne Leerzeichen geschrieben werden, ist seine eigene Entscheidung und der Grund, eines zu haben.
- Eine Seite hat die neuesten zuerst.
statusIdssind in absteigender Reihenfolge, jede höchstens einmal, höchstenslimitdavon, und jede eine Status-ID, wie der Server sie gesendet hat (36 Kleinbuchstaben). Die IDs sind UUIDv7, ihre Reihenfolge als Strings ist also die Reihenfolge der Zeit. - Der Cursor gehört dem Plugin.
nextCursorist auf der letzten Seite leer und sonst höchstens 256 Bytes druckbares ASCII ohne Leerzeichen, etwa die letzte ID der Seite. Der Server sendet ihn für die nächste Seite unverändert zurück, die nach dieser ID weitergeht, auch wenn Dokumente hinzukamen und verschwanden. Eine Seite, die nicht die letzte ist, kann weniger alslimitIDs enthalten. Ein Cursor, den das Plugin nicht ausgegeben hat, erhältOUTCOME_INVALID_CURSOR. - Ein Schreibvorgang zeigt sich in der nächsten Suche, und jeder Aufruf kann zweimal kommen: Das Entfernen von etwas, das nicht da ist, gelingt. Eine Engine, die Schreibvorgänge erst nach einem Refresh zeigt, lässt das Plugin darauf warten.
outcome |
Bedeutung | Was der Server tut |
|---|---|---|
OUTCOME_OK |
Der Aufruf tat, was er verlangt | Wendet die Sichtbarkeitsrichtlinie auf die IDs einer Seite an |
OUTCOME_FAILED |
Die Engine ist ausgefallen oder hat nicht geantwortet | Wiederholt einen Schreibvorgang mit seinem Job; lässt eine Suche fehlschlagen, die die Person erneut versuchen kann |
OUTCOME_INVALID_CURSOR |
Nur Search: Der Cursor ist keiner, den das Plugin ausgegeben hat |
Sagt dem Client, dass sein Cursor falsch ist |
Ein fehlendes oder unbekanntes outcome, ein fehlgeschlagener Aufruf und eine Seite, die diese Regeln verletzt, zählen als OUTCOME_FAILED, und nichts
von einer solchen Seite wird angezeigt. Ein Aufruf dauert höchstens plugin_search_timeout (standardmäßig 10 Sekunden) und 10 Sekunden, was auch immer diese
Einstellung sagt.
Medien konvertieren
Abschnitt betitelt „Medien konvertieren“Ein Medien-Plugin erledigt den schweren Teil der Verarbeitung von Uploads, sodass sie auf einer anderen Maschine laufen kann. Es gibt drei Arten, und du wählst jede für sich:
media_imagekodiert Bilder in ihre Varianten neu.media_videoremuxt Videos: Dateien mit einer Videospur, mit oder ohne Ton.media_audioremuxt reine Audiodateien.
Der Server erledigt den Rest weiterhin selbst. Er erkennt das Format jedes Uploads, unterscheidet Videos von Audiodateien, prüft jeden
Upload bei seinem Eintreffen gegen die Limits und erstellt die Vorschauen von Remote-Medien. Eine Art, deren Einstellung native bleibt, wird
im Server verarbeitet.
# 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:9000Setze media_<kind> = plugin und plugin_media_<kind>_address für jede Art, die du übergibst, und starte neu. Ein Plugin kann
mehr als eine Art übernehmen: Gib ihm für jede dieselbe Adresse. Jede Art führt höchstens zwei Aufrufe gleichzeitig aus, und jeder Aufruf dauert höchstens
plugin_media_<kind>_timeout (standardmäßig 4 Minuten), sodass ein langsames Video die Bilder nicht aufhält.
- Das Entfernen von Metadaten ist Aufgabe des Plugins. Die Uploads erreichen das Plugin so, wie sie gesendet wurden, mit ihren EXIF-Daten und
Tags, die enthalten können, wo ein Foto aufgenommen wurde. Der Server prüft das Format und die Größe jeder Ausgabe, kann aber nicht
erkennen, dass jede Spur von Metadaten weg ist.
my plugin test --kind media_imageprüft, dass der Standort seiner Testdateien nicht zurückkommt; prüfe den Rest im Plugin. - Einfaches TCP sendet die Uploads unverschlüsselt. Die Medienarten akzeptieren
http://, mit einer Warnung beim Start. Uploads mit ihren Metadaten überqueren das Netzwerk dann im Klartext, und nichts authentifiziert eines der beiden Enden: Jeder in diesem Netzwerk kann sie lesen oder für das Plugin antworten. Verwende einen Unix-Socket oderhttps://, es sei denn, das Netzwerk gehört dir allein. - Der Server vertraut der Ausgabe nicht. Er erkennt das Format jeder Ausgabe an ihrem Inhalt, nie an dem, was das Plugin angibt, und liefert sie mit dem Content-Type und der Dateiendung dieses Formats aus. Er dekodiert jede Ausgabe unter denselben Limits wie einen Upload und prüft, dass sie in ihre Größe passt. Eine Ausgabe, die größer ist als angegeben oder als diese Limits, ein Format hat, das das Plugin nicht angegeben hat, oder ein Format, das die Variante nicht aufnimmt, lässt den Upload als eine Datei fehlschlagen, die der Server nicht verarbeiten kann.
- Ein Fehler ist eine Verzögerung. Wenn das Plugin ausgefallen ist oder fehlschlägt, versucht der Job es später erneut, wie beim eingebauten Prozessor. Eine Aktion, die das Bild eines eigenen Emojis sofort braucht, etwa das Kopieren eines Remote-Emojis oder das Annehmen einer Anfrage dafür, schlägt fehl, solange das Plugin es tut.
Der Vertrag
Abschnitt betitelt „Der Vertrag“Der Dienst ist my.plugin.media.v1.MediaService, mit den RPCs Process für ein Bild und Remux für eine Video- oder Audiodatei.
Beide streamen in beide Richtungen, das Plugin braucht also eine Connect- oder gRPC-Bibliothek und HTTP/2: proto oder grpc, über TLS mit ALPN
h2 oder über unverschlüsseltes HTTP/2 (h2c) auf einem Unix-Socket oder einfachem TCP.
Ein Aufruf ist halbduplex:
- Der Server sendet einen
head: die Limits und, bei einem Bild, seinen Zweck, die Boxen seiner drei Größen und seinen Fokus- punkt. Die Datei folgt inchunk-Nachrichten von höchstens 1 MiB. Der Server schließt dann seine Seite. - Das Plugin antwortet mit einem
head, dessenoutcomedas Ergebnis ist. MitOUTCOME_OKenthält der Head vonProcessaußerdem die Abmessungen des Bildes nach seiner EXIF-Ausrichtung und den Blurhash der kleinen Standbild-Ausgabe. - Für jede Ausgabe sendet das Plugin einen
part, der die Ausgabe benennt und ihr Format, ihre Abmessungen und ihre Länge angibt, gefolgt vonchunk-Nachrichten von höchstens 1 MiB.
Process gibt die kleine, mittlere und große Standbild-Ausgabe zurück und die drei bewegten eines Bildes mit mehr als einem
Frame. Die kleine und die mittlere Ausgabe sind WebP; die große Standbild-Ausgabe ist ein JPEG oder ein PNG (bei einem eigenen Emoji immer ein PNG),
und die große bewegte ein GIF. Remux gibt die Datei in ihrem eigenen Container ohne Metadaten zurück und das Titelbild, das sie
einbettet, falls vorhanden. Der Server liest von Process höchstens das Doppelte des Bildlimits und von Remux das Videolimit für die
Datei und das Bildlimit für ihr Cover.
outcome |
Bedeutung | Was der Server tut |
|---|---|---|
OUTCOME_OK |
Die Ausgaben folgen | Prüft sie und speichert sie |
OUTCOME_TEMPORARY |
Das Plugin ist fehlgeschlagen | Versucht den Job später erneut |
OUTCOME_UNSUPPORTED_FORMAT, OUTCOME_UNSUPPORTED_CODEC, OUTCOME_TOO_LARGE, OUTCOME_DIMENSIONS, OUTCOME_CORRUPT, OUTCOME_TOO_LONG |
Die Datei ist nicht akzeptabel | Markiert den Upload als fehlgeschlagen |
Ein fehlendes oder unbekanntes outcome und ein fehlgeschlagener Aufruf zählen als OUTCOME_TEMPORARY.
Ein Plugin ohne Bibliothek
Abschnitt betitelt „Ein Plugin ohne Bibliothek“Mit json braucht ein Plugin allein einen HTTP-Server und eine JSON-Bibliothek. Ein RPC ist ein POST an
/<package>.<Service>/<Method> mit Content-Type: application/json, und das Plugin antwortet mit 200 und einem JSON-Objekt:
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"}Das JSON folgt dem Standard-Mapping von proto3:
- Ein
int64ist ein Dezimal-String,bytessind Base64, und ein Enum ist sein Name. - Ein Feld mit seinem Nullwert darf fehlen, in beide Richtungen. Ein Plugin muss ein fehlendes Feld als null lesen.
- Der Server ignoriert Felder, die er nicht kennt.
- Ein Ergebnis ist das
outcomeder Antwort. Ein fehlendes oder unbekanntesoutcomeist ein Fehler, nie ein Erfolg. - Ein Plugin, das fehlschlägt, antwortet mit einem HTTP-Fehler oder mit
{"code":"unavailable"}von Connect mit dem passenden Status. Der Job versucht es erneut.
Connect-Timeout-Ms und Connect-Protocol-Version dürfen ignoriert werden.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt