Die Einstellungsdatei pss.json

Die Seite beschreibt das Format der Datei pss.json: wie das Dokument aufgebaut ist, was der Dienst beim Lesen annimmt und was beim Schreiben verloren geht. Sie richtet sich an alle, die die Datei direkt bearbeiten oder die Einstellungen auf einen anderen Knoten übertragen.

Eine Änderung an der Datei wirkt ab dem nächsten Start. Um die Konfiguration eines laufenden Dienstes zu ändern, verwenden Sie die Weboberfläche oder die HTTP API (Steuerung über die HTTP API) — nur sie wenden eine Änderung sofort an und melden das Ergebnis.

Die Schritt-für-Schritt-Verfahren zum Bearbeiten, Prüfen und Übertragen — Einstellungen bearbeiten, prüfen und übertragen.

Was diese Datei ist

pss.json ist die Arbeitsdatei der Einstellungen im Verzeichnis /opt/pss/config. Die Ladereihenfolge, der Rückfall auf pss_back.json und pss_default.json sowie das Archiv beschädigter Dateien im Verzeichnis bad/ sind in Verhalten beim Start und bei Konfigurationsfehlern beschrieben.

Eine Folge dieser Reihenfolge sollte man im Kopf behalten, bevor man die Datei im Editor öffnet: ein einziger unannehmbarer Wert kostet sämtliche Streams. Die Datei wird nicht stückweise repariert — sie wird als Ganzes abgewiesen, und der Rückfall führt zu pss_default.json, in der es überhaupt keine Streams gibt. Die Sicherungskopie pss_back.json existiert nur dort, wo die Einstellungen wenigstens einmal über die Weboberfläche wiederhergestellt wurden (Wartung); eine regelmäßige Sicherung führt der Dienst nicht. Genau deshalb wird die Datei geprüft, bevor der Dienst sie liest.

Die Datei ist keine vollständige Beschreibung der Konfiguration: sie enthält nur die Abweichungen von den Werten, mit denen das Produkt gebaut wurde. Was daraus folgt, steht im nächsten Abschnitt; es ist das Wichtigste, was man vor dem Bearbeiten verstanden haben muss.

Im selben Verzeichnis liegt pss.properties — die globalen Parameter des Prozesses (Pfade zu Daten und Protokollen und Ähnliches). Es ist eine Datei der Form „Schlüssel=Wert“ mit eigener Syntax, mit JSON hat sie nichts zu tun, und nichts von dem hier Gesagten gilt für sie.

In der Datei stehen nur die Abweichungen von den Standardwerten

Beim Schreiben der Datei überspringt der Dienst jeden einfachen Wert, der dem Standardwert entspricht. Gespeichert werden nur die Abweichungen.

Daraus folgen drei Dinge, die alle in der Praxis vorkommen:

• An der Datei lässt sich nicht ablesen, wie der Dienst eingestellt ist. Ein fehlender Schlüssel bedeutet den Standardwert, und dieser Wert selbst steht nirgends in der Datei. Um die geltende Konfiguration vollständig zu lesen, fragen Sie sie beim laufenden Dienst über die HTTP API ab: dort werden alle Schlüssel zurückgegeben, auch die auf ihrem Standardwert verbliebenen.

• Einen Schlüssel mit seinem Standardwert zu schreiben ist zwecklos. Ein solcher Wert wird angenommen und verschwindet beim nächsten Speichern der Datei.

• Ändert sich ein Standardwert zwischen Versionen, ändert sich das Verhalten stillschweigend. Hat der Knoten diesen Schlüssel nie überschrieben, steht er nicht in der Datei — und nach einem Update arbeitet er ab dem allerersten Start mit dem neuen Standardwert, und die Datei sagt dazu nichts. Das ist das größte Risiko beim Übertragen von Einstellungen zwischen Versionen, und an der Datei selbst ist es nicht zu erkennen. Eine solche Änderung lässt sich nur auf einem Weg sehen: indem man die geltende Konfiguration beider Versionen über die HTTP API liest, wo auch die Standardwerte zurückgegeben werden.

Das Überspringen betrifft nur einzelne Werte. Die Abschnitte und die Listen selbst werden immer geschrieben, auch wenn innen nichts übrig bleibt: "user-default": {} ist ein Abschnitt, dessen Schlüssel alle auf ihren Standardwerten stehen, und "accept-stream": [] ist eine leere Liste, nach derselben Regel geschrieben. Leere Klammern sagen weder, dass die Einstellung gesetzt wurde, noch, dass sie übersprungen wurde: sehen Sie auf die Bedeutung des konkreten Schlüssels.

Aufbau des Dokuments

Das Dokument ist ein JSON-Objekt. Seine Mitglieder der obersten Ebene sind die Abschnitte der Einstellungen:

Abschnitt	Typ	Was es beschreibt
server	Objekt	Name und Rolle des Knotens, Protokollierung, Wartung.
cluster	Objekt	Meshwork: Adressen, Namen und Secrets der benachbarten Knoten.
user-default	Objekt	Reserviert, enthält noch keine Schlüssel.
user	Array	Die Konten der Stream-Empfänger und Partner.
web-server	Objekt	Die Weboberfläche und ihre Konten.
http-server	Objekt	Die Auslieferung von Streams über HTTP.
epg-server	Objekt	Die Auslieferung des Programmführers.
cs	Objekt	Externe Server zur Teilnehmerverwaltung.
mosaic	Objekt	Einschalten der Mosaikansicht.
epg	Objekt	Die Erfassung des Programmführers und seine Quellen.
alerter	Objekt	Die Schwellwerte der Alerts und die Zustelladressen.
acme	Objekt	Der automatische Bezug von Zertifikaten.
dvb-adapter	Array	DVB-Empfangskarten.
dvr-storage-list	Objekt	Speicher des DVR-Archivs.
stream	Array	Streams.
stream-adaptive	Array	Gruppen für adaptive Bitrate.

Arrays der obersten Ebene enthalten immer Objekte. Innerhalb von Abschnitten und Einträgen kommen auch einfache Wertelisten vor — Zahlen und Zeichenketten; dazu siehe Gepaarte Arrays werden nach Position einander zugeordnet. Die Objekte der Arrays enthalten ihrerseits verschachtelte Arrays von Objekten, die größte Tiefe des Dokuments beträgt daher drei Ebenen:

stream[]  ->  input[]   ->  die Schlüssel eines Eingangs
          ->  output[]  ->  die Schlüssel eines Ausgangs

Die Schlüssel der einfachen Abschnitte sind ausnahmslos optional, und das Fehlen eines ganzen Abschnitts ist kein Fehler.

Array-Einträge sind die Ausnahme. Neben id muss jeder Eintrag seine eigenen Ankerschlüssel führen: ein Stream — stream-name, ein Ein- und ein Ausgang — type und die Adresse oder den Pfad des gewählten Transports, eine Empfangskarte — name, ein Speicher — name und dir-path, ein Konto der Weboberfläche und des Programmführers — login und password, eine Quelle des Programmführers — name und source. Fehlt einer davon, wird die gesamte Datei verworfen. Das Schema prüft diese Schlüssel, eine Prüfung vor dem Start fängt einen solchen Eintrag also ab.

Das Nachschlagewerk zu den einzelnen Schlüsseln — Typ, Bereich und Standardwert jedes einzelnen — steht im Referenzdokument zur HTTP API (Referenzdokumente). Hier wird es bewusst nicht wiederholt: zwei Kopien eines Nachschlagewerks laufen binnen einer Ausgabe auseinander.

Was der Dienst beim Lesen der Datei tut

Das Lesen ist bewusst ungleichmäßig angelegt: in manchen Fällen verzeiht der Dienst den Fehler, in anderen weist er die ganze Datei zurück — seine erste Aufgabe ist es, den Knoten hochzubringen. Genau darin liegt der Unterschied zwischen einem Tippfehler, den Sie bemerken, und einem, den Sie nicht bemerken.

Wird angenommen, aber nicht so, wie es der Bearbeiter gemeint hat

Was in der Datei steht	Was der Dienst tut
Unbekannter Schlüssel	Wird ignoriert. Ins Protokoll wird eine Warnung mit dem Namen des Schlüssels und des Abschnitts geschrieben, an den er gerichtet ist (bei einem Array-Eintrag wird das Array genannt, nicht der Eintrag selbst). Die Einstellung, die Sie ändern wollten, ändert sich schlicht nicht, und ein Tippfehler im Schlüsselnamen ist nicht sichtbar, solange das Protokoll nicht gelesen wurde. Aus der Datei verschwindet der Schlüssel beim nächsten Speichern der Konfiguration, löst ein Speichern aber nicht selbst aus und kann lange in der Datei liegen bleiben.
Ein Schlüssel fehlt	Es gilt der Standardwert. Kein Fehler.
Ein Abschnitt fehlt	Alle ihre Schlüssel nehmen ihre Standardwerte an. Kein Fehler.
Derselbe Schlüssel zweimal in einem Abschnitt	Der letzte gewinnt stillschweigend. Weder Fehler noch Warnung.
Eine Zahl oder true und false in Anführungszeichen	Wird angenommen: der Wert wird als Text gelesen und ausgewertet. Das Schema lehnt einen solchen Wert allerdings ab, deshalb schreibt man Zahlen und Kennzeichen ohne Anführungszeichen.
Eine Zahl außerhalb des Bereichs	Wird auf die nächste Grenze gesetzt, mit einer Warnung im Protokoll, die Schlüssel, gelesenen Wert und angewandte Grenze nennt. Nach dem Laden speichert der Dienst die Datei mit dem korrigierten Wert erneut, beim nächsten Start wiederholt sich die Warnung daher nicht. Derselbe Wert über die HTTP API gesendet wird nicht korrigiert, sondern mit einem Fehler abgelehnt.
Ein Array dort, wo ein einzelner Wert erwartet wird	Wird vollständig ignoriert, ohne eine einzige Protokollzeile. Die Einstellung bleibt auf ihrem Standardwert, und es erscheint keinerlei Diagnose.

Formfehler rund um Listen und ein wiederholter Schlüssel sind die Fälle, die völlig lautlos durchgehen: das Protokoll sagt dazu nichts. Sie sind das Hauptargument dafür, die Datei vor dem Start gegen das Schema zu prüfen.

Bemerkung

Unbekannt ist auch ein Schlüssel, den diese Ausgabe nicht unterstützt. Auf einem Knoten, dessen Ausgabe DVB nicht empfangen kann, wird der Abschnitt dvb-adapter einer übertragenen Datei vollständig unbekannt: eine Warnung im Protokoll — und beim nächsten Speichern verschwindet er aus der Datei.

Wird samt der ganzen Datei zurückgewiesen

Jeder dieser Fälle bricht das Laden ab. Die Datei wird in das Verzeichnis bad/ verschoben, und der Dienst geht zur nächsten Datei der Reihe über (Verhalten beim Start und bei Konfigurationsfehlern).

Was in der Datei steht	Erläuterung
Ein JSON-Syntaxfehler	Jeder beliebige.
Der Wert null	Überall und bei jedem Schlüssel. null wird nie angenommen: um eine Einstellung auf ihren Standardwert zurückzusetzen, löscht man den Schlüssel.
Eine falsche Form des Wertes	Ein Objekt dort, wo ein einzelner Wert erwartet wird; ein einzelner Wert dort, wo ein Objekt oder eine Liste von Objekten erwartet wird.
Eine Zahl oder ein fremdes Wort anstelle eines Kennzeichens	Logische Schlüssel nehmen nur true und false an — mit oder ohne Anführungszeichen. Weder 1 und 0 noch "yes" und "no" werden angenommen.
Eine zu lange Zeichenkette	Längenbeschränkungen werden, anders als Zahlenbereiche, nie gekürzt.
Eine Dezimalzahl dort, wo eine ganze Zahl verlangt wird	Der Wert lässt sich nicht als ganze Zahl auswerten, und das Laden bricht ab. Dasselbe gilt für eine Zeichenkette, die sich nicht als Zahl lesen lässt.
Ein Array-Eintrag ohne Ankerschlüssel	Neben id muss ein Eintrag seine eigenen Pflichtschlüssel führen (Aufbau des Dokuments).
Ein Array-Eintrag ohne id	Der Bezeichner ist Pflicht. Die Ausnahme ist das Array stream: dort wird ein fehlendes id als 0 gelesen, und das ist ein zulässiger Wert, deshalb wird nur der zweite Eintrag ohne Bezeichner abgewiesen, als Wiederholung.
Ein doppeltes id	Zwei Einträge eines Arrays mit demselben Bezeichner.
Die Wiederholung eines als eindeutig deklarierten Wertes	Etliche Arrays verlangen die Eindeutigkeit eines Schlüssels unter ihren Einträgen: Kontonamen, Namen und Pfade der Speicher, Streamnamen, Adressen der Quellen und weitere.
Ein leerer Wert dort, wo Text verlangt wird	Innerhalb von Array-Einträgen ist diese Anforderung streng; in den einfachen Abschnitten wird sie nicht überall eingehalten, und auf die Nachsicht sollte man sich nicht verlassen.
Ein Wert, der die Prüfung des Abschnitts nicht bestanden hat	Ein Teil der Abschnitte prüft seine Werte als Ganzes, und auch eine solche Prüfung bricht das Laden ab: unzulässige Zeichen oder Überschreitung der Länge im Knotennamen und im Domänennamen, eine unbekannte Protokollierungsstufe, eine falsch geschriebene zusätzliche Domäne, eine abweichende Anzahl von Einträgen in den gepaarten Meshwork-Arrays, eine abweichende Länge der Listen der Namen und Werte von Umgebungsvariablen.

Das Protokoll gehört zum Verfahren

Die Fehler der ersten Tabelle verhindern den Start nicht, die der zweiten brechen ihn ab. Der einzige Ort, an dem die ersten sichtbar sind, ist das Protokoll nach dem ersten Start. Jede Zeile über einen ignorierten Schlüssel oder einen auf die Grenze gesetzten Wert bedeutet, dass die Datei etwas anderes sagt als das, was Sie hineingeschrieben haben.

Regeln, die in der Datei nicht zu sehen sind

Das sind Eigenschaften des Lesens, nicht der Syntax. Die Datei kann einwandfreies JSON sein, alle Prüfungen des vorigen Abschnitts bestehen und trotzdem etwas anderes bedeuten, als sie aussieht.

Die Reihenfolge der Schlüssel innerhalb eines Objekts ist bedeutsam

Die Schlüssel werden in der Reihenfolge angewandt, in der sie geschrieben sind. An mehreren Stellen bestimmt ein Schlüssel, welche Schlüssel im selben Eintrag weiter unten überhaupt existieren, und muss deshalb vor ihnen stehen. Ein Schlüssel, der über seinem bestimmenden Schlüssel steht, ist im Moment des Lesens noch nicht erkannt und wird als unbekannt verworfen — mit einer Warnung im Protokoll und ohne Ladefehler.

So funktionieren:

• type in einem Ein- oder Ausgangseintrag — er wählt den Transport und alles, was dazu gehört;

• mpts und stream-name in einem Stream-Eintrag. mpts wählt die Art des Streams und muss unter anderem den Arrays input und output vorausgehen, während stream-name die Parameter für OTT, Archiv und Multiplex öffnet, wenn im Eintrag kein Schlüssel mpts steht. Der von mpts übernommene Standardwert des Schlüssels enable-mosaic wird im Moment des Lesens von mpts endgültig festgelegt (fehlt er, dann von stream-name): ein ausdrücklich gesetztes enable-mosaic oberhalb dieser Stelle wird von diesem Wert überschrieben, unterhalb bleibt es erhalten;

• type und mode in einem DVB-Karteneintrag — zusammen bestimmen sie den Satz der Konfigurationsparameter, und beide müssen vor dem Schlüssel name stehen.

Eine Ausnahme von der allgemeinen Regel: stehen die Arrays input und output oberhalb von mpts, werden Ein- und Ausgänge wie für einen Stream mit einem Programm aufgebaut, und ein Typ, der nur für einen Stream mit mehreren Programmen zulässig ist, führt zur Zurückweisung der ganzen Datei statt zu einer Warnung.

Eine vom Dienst selbst geschriebene Datei erfüllt diese Regeln immer: der Dienst gibt die Schlüssel in einer festen, sicheren Reihenfolge aus. Verwundbar ist nur eine Datei, deren Reihenfolge von Hand geändert wurde. JSON Schema kennt keinen Begriff von Reihenfolge, das Schema prüft dies also nicht. Die praktische Regel ist einfach: nichts umstellen — behalten Sie die Reihenfolge bei, in der der Dienst die Datei geschrieben hat.

Bezeichner werden von Hand vergeben

Jeder Eintrag jedes Arrays hat einen Schlüssel id. Bezeichner werden nur beim Anlegen eines Eintrags über die HTTP API automatisch vergeben; beim Lesen der Datei vergibt sie niemand.

Ein von Hand hinzugefügter Eintrag muss daher ein ausdrückliches id führen:

• er ist in jedem Array Pflicht — ohne ihn wird die gesamte Datei abgewiesen;

• er muss innerhalb seines Arrays eindeutig sein;

• der kleinste zulässige Wert ist überall 1, außer im Array stream, wo auch 0 zulässig ist.

Für das Array stream ergibt sich daraus eine Falle: ein fehlendes id wird dort als 0 gelesen, also als echter Bezeichner. Der erste Eintrag ohne id geht durch, der zweite kollidiert mit ihm und verwirft die ganze Datei. Aus demselben Grund wird ein Stream mit id 0 überhaupt ohne id-Zeile in die Datei geschrieben — das ist kein Schreibfehler, sondern die Folge davon, dass null hier eben der Standardwert ist.

Die Eindeutigkeit von Bezeichnern lässt sich in JSON Schema nicht ausdrücken, dies ist also eine der wenigen Regeln, die das Schema nicht für Sie prüft. Ein fertiger Befehl zum Auffinden von Wiederholungen steht in Die Prüfungen, die das Schema nicht vornimmt.

Die Reihenfolge der Einträge in einem Array bleibt nicht erhalten

Die großen Listen sortiert der Dienst bei jedem Lesen, jede nach ihrem eigenen Schlüssel: Streams nach dem Anzeigenamen, die Ein- und Ausgänge eines Streams nach dem Ordnungsschlüssel, Konten nach dem Login, Speicher und Empfangskarten nach dem Namen. In welcher Reihenfolge Sie solche Einträge auch schreiben, die gespeicherte Datei wird abweichen. Legen Sie in ihre Reihenfolge keine Bedeutung: wo die Abfolge wichtig ist, gibt es dafür einen eigenen Schlüssel.

Die Regel gilt nicht durchgängig, und auf zwei Ausnahmen lohnt es sich zu achten:

• einige Listen behalten die Reihenfolge aus der Datei bei — insbesondere die Gruppen für adaptive Bitrate und die Server zur Teilnehmerverwaltung;

• einfache Wertelisten werden nie umsortiert. Das ist wesentlich: gerade auf ihrer Reihenfolge beruhen die gepaarten Arrays (Gepaarte Arrays werden nach Position einander zugeordnet).

Gepaarte Arrays werden nach Position einander zugeordnet

Mehrere Einstellungen werden durch parallele Arrays ausgedrückt, die nach Nummer einander zugeordnet werden: Eintrag N des einen Arrays gehört zu Eintrag N der übrigen. So funktionieren die Adressen, Namen und Secrets der benachbarten Meshwork-Knoten, die Namen und Werte von Umgebungsvariablen sowie die Listen „war — wurde“ bei der Neuvergabe von Bezeichnern. Löscht man einen Eintrag aus einem Array, ohne den entsprechenden Eintrag aus den übrigen zu löschen, verschiebt sich alles Nachfolgende.

Das Schema prüft, dass jedes Array Elemente des richtigen Typs enthält, nicht aber, dass die Längen der Arrays übereinstimmen. Das prüft der Dienst selbst und verwirft die ganze Datei bei abweichenden Längen bei den Meshwork-Peers, bei den Umgebungsvariablen, bei den Listen „war — wurde“ der PID-Neuvergabe (mpegts-pid-old und mpegts-pid-new), bei den Listen des Sprachwechsels (mpegts-lang-set-pid und mpegts-lang-set) und bei den Entschlüsselungsschlüsseln (biss-pnr und biss-key). Bei den vier RIST-Adressen (rist-addr-*) bricht eine Längenabweichung das Laden nicht ab, der Eingang öffnet sich aber nicht, und der Grund wird ins Protokoll geschrieben. Ein fertiger Befehl für den Abgleich steht in Die gleiche Länge gepaarter Arrays.

Kommentare werden gelesen, aber nicht bewahrt

Das Lesen lässt Blockkommentare der Form /* ... */ zu — sie sind praktisch, solange man an der Datei arbeitet. Nur diese Form: ein Zeilenkommentar // wird nicht unterstützt und macht die Datei syntaktisch fehlerhaft, verwirft sie also vollständig. Schreiben Sie aus demselben Grund die Zeichenfolge /* nicht innerhalb eines Textwertes — sie würde als Kommentarbeginn gelesen.

Kommentare überstehen kein Speichern: der Dienst baut das Dokument jedes Mal neu aus dem auf, was er im Speicher hält, das allererste Speichern löscht sie also alle. Betrachten Sie sie als Notizen für die Dauer der Bearbeitung, und schreiben Sie, was erhalten bleiben soll, in den Schlüssel note, den die meisten Abschnitte und Einträge haben.

Strenge JSON-Werkzeuge — darunter der Validator aus Einstellungen bearbeiten, prüfen und übertragen — können eine Datei mit Kommentaren nicht auswerten. Vor der Prüfung entfernt man die Kommentare.

Bedingte Schlüsselsätze

Zwei Schlüssel wirken als Schalter, die bestimmen, welche Schlüssel neben ihnen zulässig sind:

• In Ein- und Ausgangseinträgen wählt type den Transport. Jeder Transport hat seinen eigenen Satz von Schlüsseln; ein Schlüssel eines anderen Transports wird nicht erkannt.

• In DVB-Karteneinträgen wählt type das Sendesystem und mode die Betriebsart. Zusammen bestimmen sie den Satz der Konfigurationsschlüssel, bis hin dazu, ob es überhaupt Schlüssel für den Konverter gibt.

Das Schema bildet diese Bedingungen ab und lehnt einen Schlüssel ab, der nicht zur gewählten Variante gehört. Der einzige Fall, den es nicht ausdrücken kann, ist ein Schlüssel, dessen Form von einem Schalter im umgebenden Objekt abhängt: in einem Stream mit mehreren Programmen wird der Entschlüsselungsschlüssel (biss-key) als Liste geschrieben, in einem Stream mit einem Programm als einzelner Wert. Das Schema nimmt beide Formen überall an, wo dieser Schlüssel vorkommt; die richtige wählt allein der Dienst.

Werte, die nicht weitergegeben werden dürfen

Die Datei speichert Passwörter und Schlüssel im Klartext. Bevor Sie die Konfiguration überhaupt jemandem übergeben — einer Kollegin, einer Supportanfrage, einem Ticketsystem, einem öffentlichen Repository —, ersetzen Sie die Werte von:

• der Kontopasswörter in den Abschnitten Weboberfläche, Programmführer und Stream-Empfänger, des Passworts des Teilnehmerverwaltungsservers sowie von Login und Passwort der Programmführerquelle;

• des eigenen Secrets des Knotens und der Secrets der benachbarten Meshwork-Knoten;

• der Passphrasen der Transporte und der Client-Passwörter der PS1- und SRT-Eingänge, des Passworts des RTSP-Eingangs, von Login und Passwort des HLS/HTTP-Eingangs;

• der Schlüssel und Schlüsselbezeichner des Inhaltsschutzes und der gemeinsamen Secrets;

• der Entschlüsselungsschlüssel;

• des Bot-Tokens des Nachrichtendienstes und des Passworts des E-Mail-Kontos;

• des Bindungsschlüssels der Zertifizierungsstelle.

Zwei Schlüssel sind nicht nach Secrets benannt, enthalten aber regelmäßig welche: die Veröffentlichungsadresse eines Ausgangs zu einer externen Plattform und die Quelladresse eines Eingangs, wenn die Zugangsdaten direkt in den Link geschrieben sind.

Die Liste wächst mit jedem neuen Transport, verlassen Sie sich also nicht darauf, dass sie vollständig ist: suchen Sie vor dem Versand der Datei darin nach password, secret, key, token und passphrase und sehen Sie jeden Link durch.

Die Datei ist nicht der einzige Weg zu diesen Werten: über die HTTP API sind sie für jedes Konto des Knotens lesbar, auch für eine Rolle mit reinem Lesezugriff (Zugang).

Warnung

Ein Secret durch eine leere Zeichenkette zu ersetzen ist nicht immer unbedenklich: ein Teil dieser Schlüssel nimmt einen leeren Wert nicht an, und die Datei wird als Ganzes abgewiesen. Setzen Sie einen offensichtlichen Ersatz von glaubwürdiger Länge ein.

Prüfung mit dem JSON Schema

Zusammen mit der Dokumentation wird eine maschinenlesbare Beschreibung der Einstellungsdatei im Format JSON Schema veröffentlicht. Sie fängt eine ganze Klasse von Fehlern ab, die der Dienst selbst stillschweigend schluckt — vor allem einen Tippfehler im Schlüsselnamen und ein Array anstelle eines einzelnen Wertes.

Zwei Schemadateien

Datei	Zweck
pss.schema.json	Streng. Jeder Schlüssel muss zu den vom Produkt deklarierten gehören. Wird für eine Datei verwendet, die für die im Kopf des Schemas genannte Version bestimmt ist.
pss.compat.schema.json	Nachsichtig. Typen, Bereiche, Aufzählungen und Pflichtschlüssel werden nach wie vor geprüft, Schlüssel jedoch, die das Produkt nicht kennt, übersprungen. Der erste Durchgang beim Übertragen von Einstellungen aus einer anderen Version, wo unbekannte Schlüssel zu erwarten und nicht verdächtig sind.

Beide Schemata tragen die Produktversion, für die sie erzeugt wurden. Eine Konfiguration wird nur sinnvoll gegen das Schema derjenigen Version geprüft, die sie lesen wird. Eine Prüfung mit dem Schema einer anderen Ausgabe gibt eine zuversichtliche und falsche Antwort.

Warnung

Das nachsichtige Schema übergeht nicht nur unbekannte Schlüssel. Die Zugehörigkeit eines Schlüssels zur gewählten Variante (Bedingte Schlüsselsätze) beruht im Schema auf demselben Mechanismus, deshalb geht bei einer nachsichtigen Prüfung auch ein echter Schlüssel durch, der in den falschen Eingangstyp, die falsche Kartenbetriebsart oder die falsche Streamart geschrieben wurde — und mit ihm bleibt auch sein eigener Bereich ungeprüft. Das nachsichtige Schema ist nur der erste Durchgang; das letzte Wort hat immer das strenge.

Bemerkung

Die Schemata gehören zum Dokumentationspaket, nicht zum Produkt: im Einstellungsverzeichnis eines laufenden Knotens gibt es keine Kopie, und sie wird dort auch nicht gebraucht. Veröffentlicht werden sie auf der Dokumentationsseite — https://doc2.pstreamer.tv/schema/, ein Verzeichnis je Version. Nehmen Sie das Schema für Ihre Version und halten Sie es auf der Maschine bereit, auf der Sie die Datei bearbeiten.

Die Adresse, die im Schema selbst im Schlüssel $id steht, ist dessen Bezeichner und keine Aufforderung, etwas herunterzuladen: die Prüfung einer Datei funktioniert auch ohne Netzzugang.

Was das Schema prüft

• Schlüsselnamen — ein Tippfehler wird zum Fehler statt zum stillschweigenden Übergehen;

• die Typen der Werte, darunter ein Array anstelle eines einzelnen Wertes;

• Zahlenbereiche und Längenbeschränkungen für Text;

• abgeschlossene Mengen zulässiger Werte;

• das Vorhandensein der Pflichtschlüssel, vor allem id und type;

• die Zugehörigkeit zu einer Variante — ein Schlüssel eines fremden Transports oder eines fremden Sendesystems wird angezeigt.

Was das Schema nicht prüft

• die Reihenfolge der Schlüssel innerhalb eines Objekts (Die Reihenfolge der Schlüssel innerhalb eines Objekts ist bedeutsam);

• die Eindeutigkeit von Bezeichnern und von als eindeutig deklarierten Schlüsseln (Bezeichner werden von Hand vergeben);

• die gleiche Länge paralleler Arrays (Gepaarte Arrays werden nach Position einander zugeordnet);

• die Form eines Schlüssels, die von einem Schalter im umgebenden Objekt abhängt (Bedingte Schlüsselsätze);

• Verweise zwischen Abschnitten — ob der per Nummer referenzierte Speicher, die Quelle oder die Karte tatsächlich existiert;

• alles, was von der Maschine abhängt: ob der Pfad beschreibbar und ob der Port frei ist.

Alles Aufgezählte prüft der Dienst selbst beim Lesen der Datei, und das meiste davon bricht das Laden ab. Das Schema verkleinert die Lücke, schließt sie aber nicht: eine bestandene Prüfung bedeutet, dass die Datei korrekt und glaubwürdig ist, nicht, dass der Dienst sie annehmen wird.

Bemerkung

Die HTTP API enthält eine Anfragefamilie /schema, die Listen zulässiger Werte und gefundener Hardware zurückgibt — die von dieser Ausgabe unterstützten Ein- und Ausgangstypen, die Sprachen, die gefundenen Karten, die Transkodergeräte. Mit der Datei pss.schema.json haben sie nichts zu tun, und eines ersetzt das andere nicht. Die Übereinstimmung in den Bezeichnungen ist nur eine Übereinstimmung.

Kompatibilität zwischen Versionen

Warnung

Abwärtskompatibilität wird nicht garantiert. Bei einer Aktualisierung können sich die Einstellungsdatei, das Schema und die HTTP API gleichermaßen ändern: Bestand und Namen der Schlüssel, Wertebereiche, Form von Anfragen und Antworten. Eine Aktualisierung überträgt die Einstellungen nicht und warnt nicht vor Abweichungen. Prüfen Sie die Datei nach jeder Aktualisierung erneut, und die Skripte, die mit der HTTP API arbeiten, ebenfalls nach jeder Aktualisierung erneut.

Einzelne Schlüssel werden zwischen Ausgaben hinzugefügt, umbenannt und entfernt, und die zulässigen Bereiche werden enger. Ein entfernter Schlüssel wird unbekannt und ignoriert, die Einstellung wirkt also schlicht nicht mehr; ein neuer Schlüssel wirkt mit seinem Standardwert, solange er nicht geschrieben ist; ein Wert, der aus einem enger gewordenen Bereich gefallen ist, wird auf die Grenze gesetzt. Über keines der drei berichtet der Dienst.

In der Datei gibt es keinen Versionsvermerk. Nichts in ihr weist auf die Ausgabe hin, die sie geschrieben hat, und der Dienst nimmt beim Lesen einer Datei aus einer älteren oder neueren Ausgabe keinerlei Umwandlung vor. Zusammen mit der Dünnbesetztheit der Datei bedeutet das, dass eine übertragene Datei so angewendet wird, wie sie ist.

Das Schema ist deshalb der einzige praktikable Weg, herauszufinden, welche Schlüssel einer vorhandenen Datei diese Ausgabe nicht mehr versteht. Prüfen Sie die Datei nach jeder Aktualisierung erneut; das Vorgehen steht in Einstellungen auf eine andere Version übertragen.