chap 5: Umsetzung — 11 Abschnitte + module-components/zip-stream/race-condition diagrams

chapters/execution/pdf-preview.tex

@@ -1,6 +1,32 @@
-\section{PDF-Modal-Vorschau und Share-Link-Previews}
+\section{PDF-Vorschau und Freigabelinks}
 \label{sec:pdf-preview}
 
-% TODO: PBI 9300 (PDF-Modal), PBI 9294 (Share-Link-Previews)
-% Pre-Signed URLs, zeitlich begrenzte Gültigkeit
-% Abbildung~\ref{fig:presigned-url}
+\subsection{PDF-Vorschau im Modal}
+
+Die Vorschau öffnet PDF-Dokumente in einem überlagerten Fenster, ohne dass sie zuvor heruntergeladen werden müssen. Sie greift dabei auf dieselbe zeitlich begrenzte Zugriffs-URL zurück, die auch dem Download zugrunde liegt — der Unterschied liegt allein darin, dass der Browser das Dokument anzeigt, statt es zu speichern. Für Dateien, die keine PDF-Dokumente sind, wird keine Vorschau angeboten.
+
+Bewusst nicht umgesetzt wurde eine Prüfung der Dateigröße. Diese Abgrenzung wurde im Approval-Termin ausdrücklich in die Anforderung aufgenommen: Das Dokument wird angezeigt, unabhängig davon, wie groß es ist. Die Begründung ist pragmatisch — jede Größengrenze wäre willkürlich, und die Betrachtung eines großen Dokuments ist kein Fehlerfall, sondern lediglich langsam. Der Browser stellt PDF-Dokumente ohnehin fortlaufend dar.
+
+\subsection{Aufbau der Freigabelinks}
+
+Ein Freigabelink verweist auf eine eigene Seite, deren Adresse den relativen Pfad des Dokuments in kodierter Form enthält. Kodiert wird dabei nur der Anteil unterhalb des Kundenordners, nicht der Kundenordner selbst. Das ist keine Sicherheitsmaßnahme — die Kodierung ist trivial umkehrbar —, sondern dient dazu, Pfadtrennzeichen und Sonderzeichen unbeschadet durch die Adresse zu transportieren.
+
+Dass der Kundenordner nicht Bestandteil des Links ist, hat dagegen sehr wohl eine Wirkung: Der Link enthält keinen Hinweis auf die Organisation und ist ohne den Kontext des angemeldeten Benutzers nicht auflösbar. Die Zuordnung geschieht ausschließlich über die Anmeldung des Aufrufers.
+
+Die Seite selbst zeigt keinen Dokumentinhalt an. Sie stellt Metaangaben für die Vorschau bereit und leitet anschließend auf die Dokumentenliste weiter, wobei die Sprungmarke auf das jeweilige Dokument gesetzt und — nach Umsetzung der Paginierung — die passende Seite angesteuert wird.
+
+\subsection{Vorschau in Messengern}
+
+Der eigentliche Zweck der Freigabeseite ist, dass ein in einem Messenger geteilter Link dort mit Titel und Symbol dargestellt wird statt als nackte Adresse. Dazu werden entsprechende Metaangaben ausgeliefert: der Dokumentname als Titel, das Typsymbol als Bild und die Adresse der Dokumentenliste als Ziel.
+
+Hier trat ein Problem auf, das sich nicht aus der Spezifikation ableiten ließ. Die Typsymbole liegen als Vektorgrafiken vor, und diese werden von den Vorschaudiensten gängiger Messenger nicht zuverlässig dargestellt. Die Symbole mussten daher zusätzlich als Rastergrafiken bereitgestellt werden, allein für diesen Zweck.
+
+Der Umstand hat eine unangenehme Nebenwirkung: Jedes Symbol existiert nun in zwei Formaten, die bei einer Gestaltungsänderung gemeinsam nachzuziehen sind. Im Pull Request wurde ausdrücklich vermerkt, dass die Rastergrafiken zu aktualisieren sind, sobald das Symboldesign endgültig feststeht.
+
+\subsection{Sichtbarkeit der Vorschaubilder}
+
+Eine Entscheidung, die erst bei der Unterstützung von URL-Dateien vollständig zum Tragen kam, betrifft die Auslieferung der Vorschaubilder. Damit ein Messenger eine Vorschau erzeugen kann, muss er das Bild abrufen können — und zwar ohne Anmeldung, da der Vorschaudienst des Messengers keine Sitzung des Benutzers besitzt. Das Bild liegt somit auf einem öffentlich erreichbaren Pfad.
+
+Solange es sich um die sieben festen Typsymbole handelt, ist das unbedenklich: Sie sind Bestandteil der Anwendung und enthalten keine kundenbezogene Information. Anders verhielte es sich bei Symbolen, die aus dem Inhalt einer Datei stammen. Aus diesem Grund wurde festgelegt, dass benutzerdefinierte Symbole aus URL-Dateien \emph{nicht} für die Vorschau ausgeliefert werden — andernfalls müsste Dateiinhalt über einen nicht authentifizierten Pfad zugänglich gemacht werden.
+
+Die Entscheidung wurde im Pull Request ausdrücklich festgehalten. Sie ist ein Beispiel dafür, dass eine an sich harmlose Funktion — ein Vorschaubild — in Verbindung mit einer anderen Funktion eine Sicherheitsfrage aufwirft, die keine der beiden für sich genommen aufgeworfen hätte.