chapters: Fliesstext auf 57 reine Textseiten kuerzen

Zwei Kompressionsdurchgaenge ueber Kapitel 2-7. Entfernt wurden
Redundanzen, Meta-Kommentare, Ueberklaerungen und Fuellsaetze;
Fakten, Namen, Daten, Entscheidungen samt Begruendung sowie alle
Abbildungen und Tabellen bleiben unveraendert.

Reine Textseiten: 78 -> 57 (Woerter 19613 -> 12451).
Gesamt-PDF: 138 -> 116 Seiten.

chapters/conception/lookup-decision.tex

@@ -3,31 +3,31 @@
 
 \subsection{Die zugrunde liegende Idee}
 
-Alle in Abschnitt~\ref{sec:lookup-research} betrachteten Ansätze versuchen, die Zuordnung zwischen Organisations-ID und Ordnername \emph{zusätzlich} irgendwo zu hinterlegen — in einem Cache, in einem Token, in Efecte oder in einer Zuordnungsdatei. Jeder dieser Ansätze führt damit eine zweite Datenhaltung ein, die mit der ersten konsistent gehalten werden muss.
+Alle in Abschnitt~\ref{sec:lookup-research} betrachteten Ansätze hinterlegen die Zuordnung \emph{zusätzlich} irgendwo — in Cache, Token, Efecte oder einer Zuordnungsdatei. Jeder führt eine zweite, konsistent zu haltende Datenhaltung ein.
 
-Die schließlich gewählte Lösung dreht die Fragestellung um. Statt die Zuordnung nachzuschlagen, wird sie \emph{berechenbar} gemacht: Wenn der Ordnername sich deterministisch aus dem Firmennamen ableiten lässt und dieser Firmenname bereits im Anmeldetoken steht, kann Houston den erwarteten Ordnernamen ohne jeden Nachschlagevorgang bestimmen. Aus der Suche wird ein direkter Zugriff.
+Die gewählte Lösung dreht die Fragestellung um: Lässt sich der Ordnername deterministisch aus dem Firmennamen ableiten und steht dieser im Token, kann Houston den Ordnernamen ohne Nachschlagevorgang bestimmen. Aus der Suche wird ein direkter Zugriff.
 
-Voraussetzung dafür ist, dass die Ordner im Speicher tatsächlich so heißen, wie Houston es erwartet. Genau hier setzt die eigentliche Entscheidung an: \textbf{Houston wird zur führenden Instanz für die Namensgebung der Kundenordner.} Weicht ein Ordner vom erwarteten Namen ab, wird nicht der Erwartungswert angepasst, sondern der Ordner umbenannt.
+Voraussetzung ist, dass die Ordner tatsächlich so heißen, wie Houston es erwartet. \textbf{Houston wird zur führenden Instanz für die Namensgebung der Kundenordner.} Weicht ein Ordner ab, wird er umbenannt.
 
-Diese Festlegung ist deshalb vertretbar, weil Houston die Ordnerstruktur ohnehin selbst anlegt (FA-13). Wenn die Anwendung neue Kundenordner erzeugt, ist es folgerichtig, dass sie auch deren Benennung verantwortet. Die Kundenbetreuer verlieren dadurch nichts: Der Ordner heißt weiterhin nach dem Kunden, nur eben in einer normalisierten Form.
+Diese Festlegung ist vertretbar, weil Houston die Ordnerstruktur ohnehin selbst anlegt (FA-13). Die Kundenbetreuer verlieren nichts: Der Ordner heißt weiterhin nach dem Kunden, nur normalisiert.
 
 \subsection{Ableitung des Ordnernamens}
 
-Der Firmenname aus dem Token kann nicht unverändert als Ordnername verwendet werden. Er kann Zeichen enthalten, die im Schlüssel problematisch sind, führende oder abschließende Leerzeichen aufweisen oder beliebig lang sein. Er wird deshalb durch eine Normalisierungsfunktion geführt, die im weiteren Verlauf als \emph{Slug} bezeichnet wird.
+Der Firmenname aus dem Token kann nicht unverändert als Ordnername dienen — er kann problematische Zeichen, führende Leerzeichen oder beliebige Länge aufweisen. Er wird durch eine Normalisierungsfunktion geführt, im Folgenden \emph{Slug} genannt.
 
-Die Normalisierung folgt zwei Leitgedanken. Sie muss \textbf{deterministisch} sein — derselbe Firmenname muss stets denselben Ordnernamen ergeben, sonst funktioniert der direkte Zugriff nicht. Und sie muss das Ergebnis \textbf{lesbar} halten, weil der Ordner in Filestash von Menschen bedient wird. Aus dem zweiten Punkt folgt eine bewusste Abweichung von der üblichen Praxis: Umlaute werden \emph{nicht} ersetzt. Eine Firma „Müller GmbH" erhält den Ordner \texttt{Müller GmbH} und nicht \texttt{Mueller GmbH}, weil der Betreuer sie andernfalls in der alphabetischen Liste an unerwarteter Stelle suchen müsste. Die Zulässigkeit solcher Zeichen in Objektschlüsseln wurde anhand der Herstellerdokumentation geprüft \autocite{aws-s3-naming, ibm-s3-naming}; die Frage war auch Gegenstand des Code-Reviews.
+Die Normalisierung muss \textbf{deterministisch} sein — derselbe Firmenname muss stets denselben Ordnernamen ergeben — und das Ergebnis \textbf{lesbar} halten, weil der Ordner in Filestash von Menschen bedient wird. Umlaute werden bewusst \emph{nicht} ersetzt: „Müller GmbH" erhält den Ordner \texttt{Müller GmbH}, nicht \texttt{Mueller GmbH}, weil der Betreuer die Firma sonst in der alphabetischen Liste an unerwarteter Stelle suchen müsste. Die Zulässigkeit solcher Zeichen in Objektschlüsseln wurde anhand der Herstellerdokumentation geprüft \autocite{aws-s3-naming, ibm-s3-naming}.
 
 \subsection{Umgang mit Namenskollisionen}
 
-Firmennamen sind nicht garantiert eindeutig. Efecte lässt zwei Organisationen mit identischem Namen grundsätzlich zu, und sobald der Ordnername aus dem Firmennamen abgeleitet wird, treffen beide auf denselben Zielnamen. Da eine Verwechslung hier unmittelbar bedeuten würde, dass ein Kunde die Dokumente eines anderen sieht, muss dieser Fall abgedeckt sein.
+Firmennamen sind nicht garantiert eindeutig. Efecte lässt zwei Organisationen mit identischem Namen zu, und beide würden auf denselben Ordnernamen treffen. Da eine Verwechslung bedeuten würde, dass ein Kunde fremde Dokumente sieht, muss der Fall abgedeckt sein.
 
-Das Konzept löst ihn nach dem Prinzip „wer zuerst kommt, mahlt zuerst": Die erste Organisation, die den Namen beansprucht, erhält ihn. Jede weitere erhält einen Ordner, dem die Organisations-ID in Klammern angehängt wird, also etwa \texttt{Beispielkunde GmbH (77)}. Dieser Name ist eindeutig, bleibt lesbar und sortiert weiterhin unmittelbar neben dem gleichnamigen Ordner.
+Die erste Organisation, die den Namen beansprucht, erhält ihn. Jede weitere erhält einen Ordner mit angehängter Organisations-ID, etwa \texttt{Beispielkunde GmbH (77)} — eindeutig, lesbar und alphabetisch neben dem gleichnamigen Ordner.
 
-Maßgeblich ist dabei eine Sicherheitsregel: Ein Zielname wird nur dann beansprucht, wenn er entweder frei ist oder ausweislich seines Markers bereits der eigenen Organisation gehört. Ein fremder Kundenordner wird unter keinen Umständen überschrieben oder umbenannt. Die Zuordnung entscheidet also immer das Metadatum, niemals der Name — der Name ist nur die Optimierung.
+Sicherheitsregel: Ein Zielname wird nur beansprucht, wenn er frei ist oder ausweislich seines Markers der eigenen Organisation gehört. Ein fremder Kundenordner wird unter keinen Umständen überschrieben. Die Zuordnung entscheidet immer das Metadatum, nie der Name.
 
 \subsection{Der resultierende Ablauf}
 
-Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren, das in Abbildung~\ref{fig:lookup-flow} dargestellt ist.
+Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren (Abbildung~\ref{fig:lookup-flow}).
 
 \begin{figure}[H]
     \centering
@@ -37,21 +37,21 @@ Aus diesen Überlegungen ergibt sich ein dreistufiges Verfahren, das in Abbildun
 \end{figure}
 
 \begin{enumerate}
-    \item \textbf{Direktzugriff.} Houston bildet den erwarteten Ordnernamen aus dem Firmennamen und ruft die Metadaten des zugehörigen Markers ab. Existiert er und trägt er die richtige Organisations-ID, ist die Auflösung mit einem einzigen Aufruf abgeschlossen. Dies ist der Regelfall.
-    \item \textbf{Kollisionsprüfung.} Schlägt der erste Schritt fehl — weil der Marker fehlt oder eine fremde Organisations-ID trägt — wird derselbe Zugriff mit dem um die Organisations-ID ergänzten Namen wiederholt. Damit ist der Kollisionsfall mit zwei Aufrufen abgedeckt.
-    \item \textbf{Rückfallebene.} Erst wenn auch das nicht greift, kommt das ursprüngliche, lineare Verfahren zum Einsatz. Wird dabei ein Ordner mit passender Organisations-ID gefunden, trägt er offenbar einen abweichenden Namen und wird auf den kanonischen Namen umbenannt. Wird kein Ordner gefunden, existiert der Kunde im Speicher noch nicht und die vollständige Struktur wird angelegt.
+    \item \textbf{Direktzugriff.} Houston bildet den erwarteten Ordnernamen aus dem Firmennamen und ruft die Metadaten des Markers ab. Stimmt die Organisations-ID, ist die Auflösung mit einem Aufruf abgeschlossen. Dies ist der Regelfall.
+    \item \textbf{Kollisionsprüfung.} Fehlt der Marker oder trägt er eine fremde ID, wird der Zugriff mit dem um die Organisations-ID ergänzten Namen wiederholt — zwei Aufrufe für den Kollisionsfall.
+    \item \textbf{Rückfallebene.} Erst dann kommt das lineare Verfahren zum Einsatz. Wird ein Ordner mit passender ID gefunden, wird er auf den kanonischen Namen umbenannt. Wird keiner gefunden, wird die vollständige Struktur angelegt.
 \end{enumerate}
 
 \subsection{Selbstheilung}
 
-Die entscheidende Eigenschaft dieses Verfahrens liegt im dritten Schritt. Die Rückfallebene beseitigt nicht nur den unmittelbaren Fehlschlag, sondern auch dessen Ursache: Nach der Umbenennung trägt der Ordner den erwarteten Namen, und der nächste Zugriff derselben Organisation wird wieder über den Direktzugriff abgewickelt.
+Die entscheidende Eigenschaft liegt im dritten Schritt: Die Rückfallebene beseitigt nicht nur den Fehlschlag, sondern auch dessen Ursache. Nach der Umbenennung trägt der Ordner den erwarteten Namen, und der nächste Zugriff läuft direkt.
 
-Der teure Pfad wird damit pro Kunde höchstens einmal durchlaufen. Bestehende Ordner, die vor Einführung des Verfahrens angelegt wurden und beliebige Namen tragen, migrieren sich beim ersten Zugriff des jeweiligen Kunden von selbst. Eine gesonderte Migration ist nicht erforderlich.
+Der teure Pfad wird pro Kunde höchstens einmal durchlaufen. Bestehende Ordner migrieren sich beim ersten Zugriff von selbst — eine gesonderte Migration entfällt.
 
-Ebenso wenig erfordert das Verfahren eine zusätzliche Datenhaltung. Es gibt keinen Cache, der invalidiert werden müsste, kein Feld in einem Fremdsystem und keine Zuordnungsdatei. Der Zustand liegt vollständig im Speicher selbst, und die Anwendung ist zu jedem Zeitpunkt in der Lage, aus einem beliebigen Ausgangszustand den Sollzustand herzustellen.
+Das Verfahren erfordert keine zusätzliche Datenhaltung: keinen Cache, kein Feld in einem Fremdsystem, keine Zuordnungsdatei. Der Zustand liegt vollständig im Speicher, und die Anwendung kann aus jedem Ausgangszustand den Sollzustand herstellen.
 
 \subsection{Bewusst offen gelassener Bereich}
 
-Das Verfahren hat einen Preis, der bei der Entscheidung bekannt war: Die Rückfallebene ist nicht mehr nur lesend. Sie benennt Ordner um und legt sie an — und das im Rahmen einer gewöhnlichen Seitenanfrage. Da Houston in mehreren Instanzen betrieben wird, können zwei solche Anfragen gleichzeitig auf denselben Ordner treffen.
+Die Rückfallebene ist nicht nur lesend: Sie benennt Ordner um und legt sie an — im Rahmen einer gewöhnlichen Seitenanfrage. Da Houston in mehreren Instanzen läuft, können zwei Anfragen gleichzeitig denselben Ordner betreffen.
 
-Dieser Umstand wurde während der Umsetzung erkannt, in seinen Auswirkungen analysiert und als eigenes Backlog Item vom laufenden Pull Request abgegrenzt. Die Entscheidung, die Abgrenzung so vorzunehmen, wurde mit dem Team abgestimmt. Abschnitt~\ref{sec:race-conditions} behandelt die konkreten Fehlerszenarien und die erwogenen Gegenmaßnahmen im Detail.
+Dieser Umstand wurde analysiert und als eigenes Backlog Item vom laufenden Pull Request abgegrenzt. Abschnitt~\ref{sec:race-conditions} behandelt die Szenarien und erwogenen Gegenmaßnahmen.