23. Die REST-API von GNU Mailman 3

pepsi-httpd bietet die REST-API von GNU Mailman 3 unter /3.0/ und /3.1/ an. Das ist keine API eigenen Entwurfs: es ist die Schnittstelle eines anderen, nachgebaut, damit Software, die für GNU Mailman 3 geschrieben wurde, unverändert gegen Pepsi läuft. mailmanclient, Postorius und HyperKitty sind die Clients, für die sie existiert.

Implementiert ist Version 3.3.10. Diese Genauigkeit zählt: „Mailman 3“ ist kein Vertrag, denn der Attributsatz verschiebt sich zwischen Punktversionen, während der Pfad /3.1/ es nicht tut. Die Schnittstelle ist beim GNU-Mailman-Projekt unter https://docs.mailman3.org/ dokumentiert, und jene Dokumentation — nicht dieses Kapitel — ist die Spezifikation. Was folgt, ist das, was ein Betreiber braucht, um sie zu betreiben, dazu die drei Stellen, an denen Pepsi etwas Wahres antworten muss, anstatt etwas zu kopieren, das es nicht hat, und die eine Ressource, die Pepsi hinzufügt.

Bemerkung

Namensnennung. Der Ressourcenbaum, die Attributnamen, die Aufzählungswerte, die Konventionen auf der Leitung und die Fehlermeldungen sind die von GNU Mailman, urheberrechtlich geschützt durch die Free Software Foundation, und werden hier wiedergegeben, um damit kompatibel zu sein. Siehe vendor/PEPSI-VENDORING.md. Pepsi ist nicht GNU Mailman und wird vom GNU-Mailman-Projekt nicht unterstützt.

Dieses Kapitel behandelt die Schnittstelle. Mailinglisten erklärt, was die Ressourcen bedeuten (eine Liste, ein Mitglied, eine Moderationsentscheidung, eine Sammelnachricht), und sein Abschnitt Wie das Subsystem aufgebaut ist zeigt, wo diese API im Verhältnis zum /api/v1 des Betreibers und zu den öffentlichen Mitgliederseiten steht. Die Ressourcen des Archivs beschreibt Archive. Installation erklärt, wie Sie den Listener einschalten und welche Zugangsdaten er braucht; Die Verwaltungskonsole beschreibt die Browseroberflächen, die Clients desselben Modells sind; und Unterstützte Funktionen führt auf, was Pepsi überhaupt implementiert.

23.1. In diesem Baum gibt es zwei APIs

Ein Betreiber wird beiden begegnen, und sie haben nichts gemeinsam außer dem Server:

/api/v1

Pepsis eigene administrative API (Die administrative API). Ihr Publikum ist der Betreiber: die Warteschlange, der Schlüsselspeicher, die Protokolle, die Konfiguration. Sie hat Konten, Scopes, Sitzungen, Bearer-Token und CSRF, ihre Sammlungen sind {items, total, limit, offset} und ihre Fehler {code, hint, detail}.

/3.0/ und /3.1/

Diese hier. Ihr Publikum ist Mailinglisten-Software. Sie hat ein einziges gemeinsames Passwort und keine Scopes, ihre Sammlungen sind {start, total_size, entries} und ihre Fehler sind die von Falcon: {title, description}.

Sie sind absichtlich nicht vereinheitlicht. Der ganze Wert dieser einen liegt darin, dass ihre Formen nicht die unseren zum Verbessern sind.

23.2. Wo sie angeboten wird

Nur auf einem Listener mit dem Flag LIST_API = yes. Auf jedem anderen Listener antworten die Routen /3.0/ und /3.1/ mit einem einfachen 404, Byte für Byte das, was jeder unbekannte Pfad erhält, sodass ein öffentlicher Listener nicht danach abgetastet werden kann, ob die API in dieser Installation aktiviert ist.

Hier gilt dieselbe Regel wie für die administrative API, und aus demselben Grund: Die Zugangsdaten sind ein einziges statisches Passwort, das daher kein Klartextnetz überqueren darf.

  • ein TLS-Listener ist immer erlaubt;

  • ein Unix-Socket-Listener ist immer erlaubt (er verlässt den Rechner nie);

  • ein TCP-Listener im Klartext ist nur auf einer Loopback-Adresse erlaubt;

  • ein von systemd aktivierter Socket im Klartext wird verweigert, weil der Server nicht sehen kann, wo systemd ihn gebunden hat.

Ein Listener, der das Flag verlangt, aber anderswo gebunden ist, bietet die API nicht an, und pepsi-httpd sagt das beim Start laut, anstatt still zu versagen.

[pepsi-httpd-listener-mailman]
# What every existing mailman.cfg-shaped client already points at.
BIND_TO = 127.0.0.1:8001
MODE = plain
LIST_API = yes

[pepsi-list]
API_USER = restadmin
API_PASS = a-long-random-string

Warnung

API_USER und API_PASS sind ein gemeinsames Zugangsdatenpaar für den ganzen Server. Wer es besitzt, kann jede Liste, jedes Abonnement und jeden Benutzerdatensatz lesen und ändern. Das ist das Modell von upstream und keine Vereinfachung davon; halten Sie den Listener auf Loopback oder hinter TLS, und verwenden Sie das Passwort nirgends sonst. pepsi-httpd verweigert den Start, wenn ein Listener die API verlangt und die Zugangsdaten unvollständig sind: Eine API, deren gesamtes Autorisierungsmodell dieses Passwort ist, ohne eines anzubieten, ist kein eingeschränkter Betriebsmodus. Legen Sie API_PASS über eine @inline-secret@-Direktive in ein secrets.d-Fragment, statt es direkt in die für alle lesbare pepsi.conf zu schreiben. Findet pepsi-setup run das Passwort direkt in der Datei, verschiebt es das Passwort nach secrets.d/pepsi-list.secret (siehe Mail-Appliances speichern Geheimnisse für alle lesbar oder ungeschützt).

23.3. Authentifizierung

Die API verwendet HTTP-Basic-Authentifizierung gegen dieses eine Paar, in konstanter Zeit verglichen. Es gibt keine Sitzungen, keine CSRF-Token, keine benutzerbezogenen Konten und keine Tokenausgabe: Ein Client sendet Authorization: Basic ... bei jeder Anfrage. Ein Fehlschlag ist 401 mit

WWW-Authenticate: Basic realm="mailman3-rest",charset="utf-8"

und diese Realm-Zeichenkette ist die von upstream, weil ein Client sie anzeigen kann.

Pepsi fügt einen Ratenbegrenzer hinzu, den upstream nicht hat. Er ist eine Obermenge und kann einen korrekten Client nicht brechen. Eine Kompatibilitätssuite schickt jedoch Hunderte Anfragen in wenigen Sekunden, daher ist der Standard absichtlich hoch: 3000 Anfragen pro Minute und Quelladresse, einstellbar mit [pepsi-list] API_RATE_LIMIT. Ein 429 von dieser API stammt von Pepsi, nicht von Mailman.

23.4. Die beiden Versionen unterscheiden sich in vier Punkten

Viele nehmen fälschlich an, dass sie sich nur in einem Punkt unterscheiden:

  1. die sechs *_uri-Vorlagenattribute sind in /3.0/ Listenattribute und fehlen in /3.1/, das sie stattdessen über /uris erreicht;

  2. /templates/... existiert nur in /3.0/; /uris/..., /lists/<id>/uris, /domains/<host>/uris und /plugins existieren nur in /3.1/. Jedes davon ist in der anderen Version ein 404;

  3. Identifikatoren werden unterschiedlich serialisiert. /3.0/ gibt eine UUID als uuid.int aus, eine Dezimalzahl mit bis zu neununddreißig Stellen; /3.1/ gibt uuid.hex aus, eine Zeichenkette. Das betrifft member_id, user_id und jeden daraus gebauten self_link, und es ist der Grund, weshalb /3.1/ überhaupt existiert – die Ganzzahlform ist nicht in jeder JavaScript-Laufzeitumgebung darstellbar;

  4. jeder self_link und jedes Location trägt sein eigenes Versionspräfix.

23.5. Vorlagen-URIs

Eine Vorlagenüberschreibung ist eine URI, die der Server abruft, gleich über welche Version sie geschrieben wurde: als *_uri-Attribut in /3.0/ oder über /uris in /3.1/. Wer die REST-Zugangsdaten hält, bestimmt also, was der Server liest. Pepsi akzeptiert mailman: (den eingebauten Text) und http(s):, abgerufen unter den Grenzen in [pepsi-list] TEMPLATE_FETCH_*, und antwortet mit 400 auf eine file:-URI, die upstream von der eigenen Platte lesen würde. Ein file:-Datensatz, der dennoch in der Tabelle steht (von Hand geschrieben), wird nie gelesen: Die Benachrichtigung wird so gerendert, als fehlte der Datensatz.

23.6. Drei ehrliche Entsprechungen

Drei Ressourcen beschreiben Dinge, die GNU Mailman hat und Pepsi nicht hat. Keine davon ist vorgetäuscht.

/queues

Die Queues von upstream sind Verzeichnisse voller .pck-Dateien. Pepsi hat eine Tabelle: Eine Nachricht in Bearbeitung ist ein Datensatz in pepsi.workqueue an irgendeiner Stage. Diese Ressource antwortet daher mit den echten Zahlen der Nachrichten existierender Listen. in zählt alle, die noch in Bearbeitung sind, retry die für einen späteren Versuch pausierten, und bad und shunt die beiden Endzustände, die der Dispatcher nie wieder einreiht; die übrige Mail der Pipeline ist keine Queue einer Liste. Die workqueue_id steht für einen filebase, und der Tabellenname steht dort, wo ein Verzeichnis stünde.

POST /queues/in speist eine Nachricht an der Posting-Stage der Liste ein, wo sie die gesamte Posting-Kette durchläuft. Eine an bad oder shunt gesendete Nachricht wird an dieser Stage als failed bzw. timeout gespeichert, und nichts führt sie aus, so wie nichts die gleichnamigen Queues von upstream abarbeitet (eine Installation, die pepsi-failure-bouncer(1) betreibt, verwirft sie nach MIN_AGE). Eine an retry gesendete Nachricht wird als paused gespeichert, und der Dispatcher nimmt sie wieder auf. DELETE /queues/<name>/<id> entfernt einen Datensatz. Eine virgin-Queue gibt es nicht: Eine Nachricht, die Pepsi selbst verfasst, ist ein gewöhnlicher Datensatz an seiner Antwort-Stage. pepsi-queue(1) bleibt das eigentliche Werkzeug.

/plugins

Immer eine leere Sammlung. Pepsi hat keine Plugin-Schnittstelle und keine einsteckbaren Archivierer. In /3.0/ gibt es diese Ressource nicht.

/reserved

Der eigene Testhaken von upstream, den upstream selbst als nicht Teil der stabilen API kennzeichnet. GET /reserved/reset leert jede Listen- und Archivtabelle, es existiert daher nur auf einem Listener, der sich mit LIST_API_TESTING = yes ausdrücklich dafür entschieden hat; überall sonst ist es ein 404, das von einem unbekannten Pfad nicht zu unterscheiden ist, und ein Test prüft diese Voreinstellung. Es ist da, weil die Kompatibilitätssuiten den Zustand zwischen Testklassen im eigenen Prozess zurücksetzen, was ein Server in einem anderen Prozess nicht anbieten kann. Es setzt außerdem die Zähler der geleerten Tabellen zurück, sodass die erste zurückgehaltene Nachricht nach einem Reset wieder Anfrage 1 ist, wie auf der Testdatenbank von upstream. DELETE /reserved/uids/orphans ist eine erfolgreiche Leeroperation: Identifikatoren sind hier UUIDs der Version 4, und es gibt keine Waisentabelle auszudünnen.

23.7. Eine eigene Ressource von Pepsi

GET /<api>/lists/<id>/pepsi liefert die listenbezogenen Einstellungen, die Pepsi eingeführt hat (Einstellungen, die Pepsi erfunden hat). Für jede der Einstellungen search_trigram, archive_show_addresses, hold_dmarc_failures und archive_retention_days meldet es den eigenen Wert der Liste oder den Standard (null, wo die Einstellung des Servers gilt). PATCH auf denselben Pfad setzt jede davon, genau so validiert, wie pepsi-list list set-ext sie validiert; ein leerer Wert entfernt den eigenen Wert der Liste, und ein unbekannter Schlüssel ergibt 400.

Sie sind keine Attribute unter /config und dürfen keine werden: Ein PUT /config auf die ganze Ressource muss jedes schreibbare Attribut mitführen, sodass ein weiteres dort jeden Client bräche, der gegen 3.3.10 gebaut ist. Kein Client von upstream fragt diesen Pfad ab, also kann ihn keiner bemerken.

23.8. Was über die Zugangsdaten hinaus konfiguriert werden muss

[pepsi-list] RELEASE_STAGE

Der Abschnitt [stage-<name>], in dem pepsi-stage-list-post läuft. Ein Moderator, der eine zurückgehaltene Nachricht annimmt, und POST /queues/<name> setzen eine Nachricht beide dort wieder in die Pipeline, und nur die Installation weiß, wie dieser Abschnitt heißt. Ohne ihn antworten diese beiden Vorgänge mit 400 und sagen es – was besser ist, als 204 zu antworten und die Nachricht fallen zu lassen, denn ein Moderator, der eine Nachricht annimmt und zusieht, wie sie nie ankommt, kann das nicht von einem Zustellfehler unterscheiden.

[pepsi-list] DEFAULT_LANGUAGE

Die Unterkante der Präferenzkette, gemeldet von GET /<api>/system/preferences. Standard ist en.

23.9. Ein durchgearbeitetes Beispiel

Halten Sie die Zugangsdaten aus der Kommandozeile heraus: Auf einem gemeinsam genutzten Rechner stünden sie in jeder Prozessliste und in der Shell-Historie. Schreiben Sie sie stattdessen in eine Datei, und lassen Sie curl daraus lesen:

$ cat > ~/.mailman-netrc <<'EOF'
machine localhost login restadmin password a-long-random-string
EOF
$ chmod 600 ~/.mailman-netrc
$ alias mmcurl='curl -sS --netrc-file ~/.mailman-netrc'

$ mmcurl http://localhost:8001/3.1/system/versions
{"mailman_version":"GNU Mailman 3.3.10 (Tom Sawyer; implemented by Pepsi …)",
 "python_version":"…","api_version":"3.1",
 "self_link":"http://localhost:8001/3.1/system/versions",
 "http_etag":"\"…\""}

$ mmcurl -X POST --data 'mail_host=lists.example.com' \
    http://localhost:8001/3.1/domains

$ mmcurl -X POST --data 'fqdn_listname=devel@lists.example.com' \
    http://localhost:8001/3.1/lists

$ mmcurl 'http://localhost:8001/3.1/lists?count=10&page=1'

mailman_version verdient einen zweiten Blick. Es muss mit der Zeichenkette beginnen, auf die ein Client prüft, und es muss wahr sein. Es nennt daher zuerst die Version der Schnittstelle und sagt in der Klammer, wo upstream einen Codenamen einsetzt, was tatsächlich läuft. Pepsi behauptet nicht, GNU Mailman zu sein. Diese Ressource ist die einzige Stelle, an der eine Version angezeigt wird, und sie erfordert die API-Zugangsdaten (siehe Fehlendes HTTPS und fehlende Härtung über HTTP-Sicherheitsheader bei Webmail).

POST /lists/<id>/digest: bump erhöht den Band, und send und periodic laufen beide über den Versender, den auch die Kommandozeile benutzt. Eine von einem Client ausgelöste Ausgabe und eine von einem Timer ausgelöste nehmen daher denselben Codeweg und tragen dieselbe Nummerierung.

23.10. Was nicht implementiert ist

  • Eine zurückgewiesene zurückgehaltene Nachricht oder Anfrage wird verworfen, ohne die Zurückweisungsbenachrichtigung, die upstream sendet. Annehmen, Verwerfen und Zurückstellen sind vollständig.

  • Ein Abonnement, das über die API abgeschlossen wird, verschickt keine Willkommensnachricht: send_welcome_message wird angenommen und bleibt wirkungslos.

  • [mta] verp_format, verp_regexp, verp_confirm_format und verp_probes sind keine Konfiguration. Jede Kopie wird per VERP adressiert, in der Form ${bounces}+${local}=${domain} von upstream mit einem als weiteres =-Feld angehängten Authentifizierungscode (mit [pepsi-list] VERP_SECRET als Schlüssel), und Proben sind standardmäßig eingeschaltet ([pepsi-list] BOUNCE_PROBES); keine API-Ressource legt eine VERP-Adresse offen, sodass ein Client keinen Unterschied sieht.

23.11. Sie testen

tests/22-list-api-test.sh führt die eigenen Testsuiten von upstream gegen ein installiertes Pepsi aus: mailmanclient 3.3.5 (344 Doctest-Anweisungen und 36 Testfunktionen) und Postorius 1.3.13 (30 Dateien, 248 Testfunktionen), jeweils nur mit ausgetauschter Vorrichtung zum Starten des Servers. Die Ersatzstücke liegen in contrib/compat/ und sind neben den festgeschriebenen Anforderungen versioniert, sodass „unveränderte Upstream-Tests“ für alles außer der Vorrichtung wörtlich wahr bleibt. contrib/compat/run-local.sh führt dieselben beiden Suiten gegen einen Build-Baum statt gegen eine Installation aus: eine Wegwerf-Datenbank, eine Konfiguration nur mit diesem Listener und die eigenen pepsi-httpd und pepsi-dispatch des Baums, in einem privaten Netzwerk-Namensraum, damit Port 9001, den die Doctests von mailmanclient nennen, frei ist.

Beide Suiten bestehen. Was bleibt, sind strikt erwartete Fehlschläge, jeder davon ein erklärter Unterschied, der in Erklärte Unterschiede zu GNU Mailman 3 aufgeführt ist: Die Vorrichtung markiert den Test (oder, im einzigen using.rst-Doctest von mailmanclient, die einzelne Anweisung), und ein markierter Test, der zu bestehen beginnt, lässt den Lauf fehlschlagen. Die Vorrichtung verlängert außerdem die Passwörter, die die Suiten ihren Benutzern geben: Die kurzen würde Pepsi ablehnen, und in keinem dieser Tests geht es um Passwörter. Siehe Testsuite.