2.2.1 Promises

Ebenso wie die in node.js integrierten Module, verwenden auch viele externe Bibliotheken Callbacks, um Rückgabewerte asynchroner Schnittstellen zu übertragen. Dies führt bei vielen voneinander abhängigen Aufrufen zu Software, deren Programmfluss auf Grund von ineinander verschachtelten Funktionsaufrufen schwer nachzuvollziehen muss. Ebenso ist das Behandeln aller Fehlerfälle in solchen Programmen oft komplex.

Viele dieser Probleme werden durch den Einsatz von Promises [19] gelöst. Die Standard-konforme Implementierung bluebird [20] wird in EpisodeFever verwendet, da sie sehr performant ist [21] und viele Hilfsfunktionen mitliefert (um beispielsweise in node integrierte Module mit Promises zu verwenden).

2.2.2 Tests

Das Schreiben und Ausführen von automatisierten Tests wird durch mocha ermöglicht, einem Test-Framework, welches mit dem von Ruby bekannten rspec [22] vergleichbar ist. Alternativen sind Jasmine [23] oder Vows [24].

Alle drei verwenden die für Behavior-driven Development [25] typischen Bezeichnungen (Tests sind Blöcke mit den Funktionen describe und it). Während Jasmine sich sehr ähnlich zu mocha verhält und ähnliche Interfaces bietet, ist es nicht so mächtig; es fehlt beispielsweise die Unterstützung Promises als Rückgabewerte von Tests auszuwerten, was asynchrone Tests sehr verkürzt. Vows fokussiert sich auf asynchrone Tests, die parallel ausgeführt werden können. Dies scheint für Unit-Tests hilfreich zu sein, bei Integrationstests wie dem Abfragen einer REST-API und dem Überprüfen von Datenbank-Inhalten führt dies aber dazu, dass Abhängigkeiten von Tests explizit angebeben werden müssen.

Die Bibliothek chai.js [26] bietet eine Vielzahl von Hilfs-Funktionen, mit welchen Werte von Objekten überprüft werden können. Da im Projekt nur die Funktionen basierend auf expect verwendet werden, wurde zunächst überlegt, das minimlistische Modul expect.js [27] zu verwenden. Letztendlich bietet chai.js jedoch mehr Funktionen, wird aktivier entwickelt und hat eine Schnittstelle für Erweiterungen (sodass beispielsweise die Datentypen von bookshelf einfacher geprüft werden können).

Um Anfragen an den zu testenden Teil des Servers zu simulieren, wurde supertest [28] eingesetzt. Supertest basiert auf superagent [29], welches schon für den Zugriff auf externe APIs verwendet wird, wie in XML-Daten abfragen und verarbeiten beschrieben. Supertest bietet einfache Möglichkeiten zur Überprüfung von HTTP-Antworten. Es wurde um die Verwendung von Promises erweitert, sodass asynchrone Tests einfach zu schreiben sind. (Ist der Rückgabe-Wert eines Tests ein Promise, wird dieses von mocha automatisch ausgewertet.)

3.1.1 Datenbank-Schema

Aus den Ansprüchen an die API lässt sich ableiten, welche Daten zur Verfügung stehen müssen. Daraus lässt sich wiederum ein Datenbank-Schema entwerfen. Dieses sollte normalisiert und erweiterbar sein [30 S. 75–81].

Wie oben erwähnt, wurde als Alternative zu einer SQL-Datenbank auch die NoSQL-Datenbank MongoDB in Betracht gezogen. Diese eignet sich besonders, wenn zu bestimmten Datensätzen immer zusätzliche Relationen ausgelesen werden. Würden beispielsweise zu Serien immer alle Episoden geladen werden, könnte man in MongoDB die Episoden in das Serien-Dokument einbetten.

In EpisodeFever ist dies aber nicht gegeben. Episoden sollten keine eingebetteten Dokumente sein, da es möglich sein soll, die in den nächsten Tagen ausgestrahlten Episoden leicht zu bestimmen. Ebenso können Bewertungen nicht problemlos in andere Dokument eingebettet werden (z.B. als Teil der bewerteten Episode oder des bewertenden Benutzers), da man sie im Kontext eines Benutzers, einer Episode oder einer Serie abfragen können soll. Aus diesen Gründen erschien eine SQL-Datenbank die bessere Wahl zu sein.

Das Diagramm EpisodeFevers Datenbankschema stellt das verwendete Schema als gerichteten Graphen dar. Verbindung zwischen Feldern symbolisieren Relationen zwischen Tabellen (mit Foreign Keys). Die Episoden-Tabelle beinhaltet z.B. eine Referenz auf einen Eintrag der Serien-Tabelle.

Zu den vier abgebildeten Tabellen existiert auch noch eine knex_migrations-Tabelle. Diese wird von knex [17] automatisch angelegt und gefüllt, um festzuhalten, welche Schema-Migrationen in dieser Datenbank bereits durchgeführt wurden.

3.2.1 Services

Die Anwendung wurde in verschiedene Services aufgeteilt, welche möglichst isoliert von einander funktionsfähig sein sollen. Deren Code ist in einzelnen Verzeichnissen in server/services/ zu finden.

Diese Aufteilung soll es ermöglichen, einzelne Teile der Applikation einfacher überblicken und getrennt voneinander entwickeln zu können. Idealerweise sind Services so modular aufgebaut, dass sie in zukünftigen Projekten wiederverwendet werden können.

Wie in der Verzeichnisstruktur zu sehen ist, sind Kern-Bestandteile eines Services:

• der Einstiegspunkt (index.js), welcher die Schnittstellen des Services exportiert,
• das Daten-Modell (model.js über welches Abfragen und Änderungen an der Datenbank ausgeführt werden,
• Tests (tests.js), welche beschreiben, was der Service behandelt und sicherstellen, dass keine Regressionen auftreten.

3.2.2 Alternativen

Eine alternative Strukturierung ist das Gruppieren nach Typen, d.h. in Verzeichnisse wie models, controllers und specs (Tests). Dies ist beispielsweise bei Anwendungen basierend auf Ruby on Rails [12] typisch. Da dies auf den Code aber nur minimale Auswirkungen hat, ist es letztendlich Geschmacks-Sache. Wir entschieden uns für die oben beschriebe Aufteilung, da diese die inhaltliche Aufteilung in den Vordergrund stellt, nicht die strukturelle.

3.3.1 Registrierung

Die Registrierung läuft folgendermaßen ab.

Der Benutzer gibt seine Daten ein (Name, E-Mail, Password) und gibt beim Absenden diese als POST Request an den Server. Die Daten werden aus dem Request extrahiert, normalisiert und validiert.

Für die Validierung wurde die Library CheckIt [31] verwendet. Wir entschieden uns für CheckIt, da es vom selben Autor wie bookshelf und knex ist (Tim Griesser) und daher gut mit diesen zusammen arbeitet. Alternativen sind Joi oder is-my-json-valid.

CheckIt ermöglicht es, Javascript Objekte zu validieren, indem für die Daten bestimmte Formate und Anforderungen definiert werden. Diese sind z.B. bei uns, dass das Feld E-Mail auch das Format einer E-Mail Adresse hat, das Passwort aus mindestens 6 Zeichen besteht und kein Felder leer sein darf. Damit stellen wir sicher, dass keine Spam-Anmeldungen möglich sind.

Wenn die vorliegenden Daten den geforderten Standards entsprechen, wird überprüft, ob die Daten nicht bereits existieren. Sollte das nicht der Fall sein, wird das Passwort an einen Helper⁴ übergeben, der mittels bcrypt [32], einen Salt generiert und aus diesem und dem Passwort einen Hash-Wert ermittelt⁵. Zusätzlich wird ein Token für die Verifizierung erzeugt. Der generierte Hash, sowie der Token werden dann zusammen mit den eingegebenen Daten in der Datenbank hinterlegt und anschließend eine E-Mail mit einem Verifizierungs-Link versandt, welcher den Verifizierungs-Token in URL-geeigneter Form enthält.

Sobald dieser Link aufgerufen wird, wird der mit dem Token verbundene Account als verifiziert markiert. Die Registrierung ist damit abgeschlossen.

3.3.2 Login

Ursprünglich wollten wir die Open Source Library Passport [34] für die Anmeldung verwenden, doch im Laufe des Projekts haben wir festgestellt, dass dies kaum Vorteile bringt, da wir den größten Teil der Funktionalitäten trotzdem selber schreiben mussten. So stellte Passport beispielsweise nur Cookies für Sessions zur Verfügung, sodass wir die Generierung von Session-Tokens selbst schreiben mussten. Selbst für die Überprüfung der Login Daten haben wir festgestellt, dass die Benutzung von Passport keine wesentlichen Vorteile gegenüber einer selbst geschriebenen Lösung bietet und haben deshalb beschlossen, auf die zusätzliche Abhängigkeit zu verzichten, die Library nicht zu verwenden und stattdessen eine eigene Lösung zu schreiben. Wäre ein Anmeldung über Soziale Dienste wie Facebook oder Twitter vorgesehen, würde sich eine erneute Betrachtung, der Library unter Umständen lohnen, da Passport dazu eine Schnittstelle bereitstellt. Doch da dies nicht als Feature vorgesehen war, hatte das keinen Einfluss auf unsere Entscheidung.

Die Anmeldung wurde von uns auf folgende Art gelöst.

Der Benutzer gibt seine Anmeldedaten (E-Mail und Passwort) ein und gibt beim Absenden den POST Request an den Server. Die versendeten Daten werden aus dem Request extrahiert. Mit den extrahierten Daten wird zuerst überprüft, ob es in der Datenbank einen Benutzer mit der angegebenen E-Mail gibt und ob dieser Benutzer verifiziert ist. Sollte dies der Fall sein wird ein User-Objekt erstellt, welches die Informationen über den Benutzer aus der Datenbank enthält.

Ein Helper⁶ überprüft, dann ob das vom Benutzer eingegebene Passwort mit dem hinterlegten Passwort übereinstimmt. Da das in der Datenbank gespeicherte Passwort gehasht vorliegt, benutzen wir die compare Methode von bcrypt, die uns erlaubt das eingegebene Passwort mit dem gehashten Passwort abzugleichen. Stimmen diese überein wird ein Session-Token generiert und zurückgegeben. Damit ist der Anmeldeprozess abgeschlossen.

3.3.3 Verifizierung

Die Verifizierung wurde bereits bei der Planung vorgesehen, da wir sicherstellen wollten, dass die bei der Registrierung eingegebenen E-Mail-Adressen auch wirklich existieren und der Benutzer dies durch das Klicken auf einen Verifizierungs-Link bestätigt. Wir sahen diese Funktionalität deshalb als wichtig an, da wir die Erstellung von Spam-Accounts einschränken wollten.

Die Verifizierung läuft wie folgt ab.

Wie bereits vorher erläutert, wurde beim Registrieren ein Verifizierungs-Token erstellt und in der Datenbank abgelegt. Dieser Token wird dann mithilfe der Library jsonwebtoken [35] in einen sogenannten JSON-Web-Token (JWT) konvertiert (eine serialisierte und kryptographisch signierte From eines JSON-Objektes), welcher den zuvor generierten Verifizierungs-Token und die ID des Benutzers enthält. Der JWT wird dann an die vom Benutzer eingegebene E-Mail in Form eines Verifizierungs-Links gesendet.

Zum Versenden der E-Mail haben wir die Nodemailer-Library [36] benutzt, weil diese sehr leicht zu implementieren war und viele Funktionalitäten bot (um beispielsweise mit externen Mailling-Anbietern wie Sendgrid zu kommunizieren, welche neben SMTP auch weitere Funktionen über eine REST-API bieten).

Beim Aufruf des Verifizierungs-Links dekodieren wir zuerst den JWT, extrahieren daraus die Benutzer ID und den Verifizierungs-Token und überprüfen, ob die Daten in valider Form vorliegen. Dann überprüfen wir, ob der Benutzer bereits verifiziert ist und ob der extrahierte Token mit dem Token in der Datenbank übereinstimmen. Falls der Benutzer nicht bereits verifiziert und der Token korrekt ist, wird der Benutzer verifiziert und die Verifizierung ist abgeschlossen.

3.4.1 Abfragen vieler Einträge

Unter dem relativen Pfad / soll eine Liste von Einträgen abgefragt werden können. Eine triviale Variante eines solchen Endpunkts könnte wie folgt geschrieben werden (anschließend an den oben gezeigten Code der index.js):

var Show = require('./model.js');
  
  app.get('/', function (request, response) {
    Show.query()
    .then(function (shows) {
      response.send(shows);
    })
    .catch(function (error) {
      response.status(500).send({error: error});
    });
  });

3.4.2 Fehlerfälle abstrakt behandeln

Im vorigen Code-Beispiel wird ein möglicher Fehlerfall bei der Abfrage von Serien dadurch behandelt, dass eine Antwort mit HTTP-Status 500 und der JSON-Darstellung des erhaltenen Fehlers gesendet wird. Dieser Fall ist sehr allgemein, muss aber standardmäßig in jedem Endpunkt behandelt werden.

Um doppelten Code zu vermeiden, wurde die Funktion wrapRoute geschrieben (vgl. server/helpers/wrap_route.js). Diese wird statt einem direkten Callback beim Erstellen des Endpunkts verwendet und erwartet als einzigen Parameter eine Funktion, die ein Promise zurückgibt. Je nach Wert des aufgelösten Promises wird die entsprechende Antwort zurückgesendet.

Der benötigte Code für den trivialen Endpunkt von oben reduziert sich damit drastisch:

var wrapRoute = require('../../helpers/wrap_route');
  var Show = require('./model.js');
  
  app.get('/', wrapRoute(function (request) {
    return Show.query();
  }));

3.4.3 HTTP-Antworten bei Fehlerfällen

Es sollte nicht auf jeden Fehler mit HTTP-Status 500 geantwortet werden, da dieser für Internal Server Error steht und daher für Fehler steht, deren Ursache nicht genauer durch einen HTTP-Status repräsentiert werden kann. Häufige Fehlerfälle, die zusätzlich beachtet werden sollen, und ihre korrekten Status-Codes, sind [1; 37]:

• 401: Keine Zugriffsberechtigung.
• 404: Angefragte Ressource konnte nicht gefunden werden.
• 409: Daten-Konflikt (beim Erstellen eines neuen Eintrags).
• 422: Daten konnten nicht verarbeitet werden (z.B. weil eine Validierung gescheitert ist).

3.4.4 Filterung und Sortierung

Standardmäßig werden alle Einträge ausgegeben (später wird die Anzahl limitiert und Seiten-weises Abfragen eingeführt). Diese Liste kann je nach Entität mit bestimmten Filtern versehen werden, welche als Teil der URL in Form von Query-Parametern übertragen werden.

Für Serien ist beispielsweise die Abfrage /?show_ids=4,8,15,16,23,42 möglich, wodurch nur Einträge zurückgegeben werden, deren ID angegeben wurde. Da das Auslesen von Query-Paramtern und Ergänzen der Datenbank-Abfrage um die korrekten Bedingungen für viele Entitäten sehr ähnlich ist, wurden in server/helpers/query_params.js einige Hilfsmethoden dazu geschrieben.

3.4.5 Abfragen eines einzelnen Eintrags

Ähnlich wie die Abfrage nach einer Liste von Einträgen mit bestimmten IDs gestaltet sich auch die Abfrage eines einzelnen Eintrags. Jeder Eintrag ist unter der URL /:id verfügbar (wobei :id durch die ID des Eintrags ersetzt wird).

Zusätzlich zu den Feldern des Eintrags ist es bei bestimmten Entitäten auch möglich, verwandte Daten anderer Entitäten mit abzufragen, um z.B. eine Serie und die Liste der IDs aller dazugehöriger Episoden abzufragen. Diese Daten werden als Teil eines speziellen link-Attributs in der JSON-Antwort übertragen (vgl. Referenz 38).

3.4.6 Zukünftige Episoden als Kalender-Feed

Bisher liefert die Applikation auf jede Anfrage JSON-Daten zurück. Dies ist praktisch, wenn die Daten von einer Anwendung gelesen werden, die an EpisodeFever angepasst wurde (z.B. ein HTML5-basiertes Frontend für EpisodeFever). Auf Grund der beim Import ermittelten genauen Zeit-Informationen ist aber gerade bei den Episoden-Daten auch noch ein anderes Format sinnvoll: Kalender-Feeds (ics- bzw. iCal-Format).

Ein Benutzer kann einen solchen Feed in sein Kalender-Programm (z.B. Google Calendar oder Kalender von OS X) und erhält so die Termine zukünftiger Episoden der von ihm betrachteten Serien.

Das ics-Format ist ein Text-Format, welches Events (Termine) in Zeilenblöcken anhand von bestimmten Attributen beschreibt. Da es ein sehr verbreitetes Format ist (s. Standard), gibt es eine Reihe von Libraries, welche dieses aus JSON-Daten erzeugen können. Eine, welche sehr umfangreich ist, aktiv entwickelt wird und außerdem explizit Unterstützung für Zeitzonen bieten, ist cozy-ical [39].

3.5.1 Test-Daten

Eine Herausforderung beim Schreiben von Tests ist es, dynamisch Test-Daten in die Datenbank einfügen zu können. Um beispielsweise testen zu können, ob ein Entpunkt die Liste aller Episoden ausgibt, welche nach einem bestimmten Datum ausgestrahlt werden, müssen zunächst Episoden-Daten mit verschiedenen Ausstrahlungsdaten eingefügt werden.

Um dies zu vereinfachen, wurde jedem bookshelf-Model eine statische fake-Methode hinzugefügt. Diese generiert standardmäßig einen Datensatz mit zufällen Daten (mit Hilfe von faker.js [40]), es können jedoch einzelne Felder beliebig überschrieben werden.

Da fake() ein Promise mit dem zu speichernden Datensatz zurückliefert, kann das Erstellen von Test-Daten direkt innerhalb eines Tests ausgeführt werden. Sollen die Daten in allen Tests einer Test-Suite verliegen, können sie auch in einem before-Block eingefügt werden (auf der selben Ebene wie die mit it registrierten konkreten Tests). In solchen before-Blöcken werden zu Beginn einer Tests-Suite oft auch die schon in der Datenbank vorhandenen Einträge gelöscht, um konsistent testen zu können.

Im folgenden Beispiel wird eine Serie eingefügt und anschließend ein Test für /shows ausgeführt:

var request = require('supertest');
  var Show = require('./model');
  var app = require('express')();
  app.use('/', require('./index'));
  var F = require('../../helpers/faking_helpers');
  
  describe("Shows API", function () {
    var agent = request.agent(app);
  
    before(function () {
      return F.dropAllTheData()
      .then(function () {
        return Show.fake();
      })
    });
  
    it("returns a list of shows", function () {
      return agent.get('/')
      .expect(200)
      .exec()
      .then(function (res) {
        expect(res.body).to.be.an('object');
        expect(res.body.shows).to.be.an('array');
        expect(res.body.shows).to.have.length(1);
      });
    });
  });

3.6.1 XML-Daten abfragen und verarbeiten

Um mit der XML-API über HTTP zu kommunizieren, wurde superagent [29] eingesetzt. Basierend auf den von Node mitgelieferten HTTP-Client-Funktionen⁸ bietet es eine übersichtliche Schnittstelle zum Erstellen von komplexen HTTP-Requests. Um den Umgang mit asynchronen Funktionen zu vereinfachen, wurde der Prototyp von superagent um die Methode .exec() erweitert, welche ein Promise zurückgibt (siehe verwendete Technologien).

Um das Arbeiten mit den API-Antworten im XML-Format zu vereinfachen, wurde das Modul xml2js [43] ausgewählt. Dieses basiert auf dem Streaming-Parser sax-js [44] und konvertiert XML-Strukturen in JavaScript-Objekte. Hierbei werden einige Optionen angeboten, welche das resultierende Objekt stark vereinfachen können, u.a. um Knoten mit nur einem Kind als direkten Datensatz (und nicht als Array) auszugeben. Da die APIs XML-Dokumente zurückgeben, welche sehr wenig Gebrauch von verschachtelten Knoten oder Attributen machen, kann xml2js Objekte mit flacher Struktur erzeugen, welche einfach zu verwenden sind.

Die gesamte Konfiguration zur Abfrage und Verarbeitung der API-Anfragen kann in der Datei import/apis/xml_api_helper.js gefunden werden.

3.6.2 Verwenden der XML-API von TheTVDB

Jede Anfrage zu der TheTVDB-API muss mit einem API-Key versehen werden (als Teil der URL). Ein solcher Schlüssel kann über ein Formular beantragt werden.

Um die Daten einer TV-Serie auszulesen, muss zunächst die TVDB-eigene ID dieser Serie gefunden werden. Mit dieser kann dann die URL zu dem gesamten Datensatz der Serie generiert werden. Vergleiche hierzu die Abbildung zu API-Abfragen.

Obwohl die Daten der API nun als XML (bzw. JavaScript Objekt) vorliegen, müssen noch kleine Transformationen durchgeführt werden, um sie verwenden zu können. So beinhalten einige Felder zwar Zeichenketten, inhaltlich handelt es sich jedoch um Listen von Werten. Das Genre-Feld einer Serie kann beispielsweise den Wert "|Action|Adventure|Comedy|Drama|" haben.

3.6.3 Datum und Zeit einer Episode auslesen

Des Weiteren ist das Verarbeiten von Datumsformaten notwendig. Ziel ist es, jeder Episode sowohl Datum als auch Uhrzeit zuzuordnen, wann sie (zuerst) ausgestrahlt wurde. Dies ermöglicht es insbesondere, zukünftige Episoden abzufragen, z.B. um einen Kalender zu implementieren und Benutzer im Voraus zu benachrichtigen.

Die API von TheTVDB beinhaltet hierzu nur ungenaue Daten [45]. Jede Episode besitzt zwar ein FirstAired-Feld, dieses beinhaltet jedoch nur das Datum (z.B. "2009-02-03"). Die Uhrzeit der Ausstrahlung ist jedoch im Datensatz der Serie verfügbar (Airs_Time), vermutlich unter der Annahme, dass diese typischerweise nicht variiert. Das Format der Uhrzeit ist jedoch nicht eindeutig, da Werte wie "8:00 PM" verwendet werden, und keine Zeitzone angegeben wird. Es scheint immer die Zeitzone des TV-Senders, auf dem die Serie initial ausgestrahlt wird, verwendet zu werden. Da aber keine Zuordnung von Sendern zu Zeitzonen verfügbar ist, kann hierdurch auch keine genaue Zeitangabe berechnet werden.

Diese Lücke in der TheTVDB-API bedeutet für EpisodeFever, dass entweder nur unvollständige Daten verfügbar sind, oder zusätzlich Daten aus einer zweiten Quelle geladen werden müssen.

3.6.4 Kombination von TheTVDB und TVRage

Eine weitere Quelle für Daten zu TV-Serien ist TVRage [46]. Diese Webseite bietet ähnliche Daten wie TheTVDB und wird (zum Teil) ebenfalls von Freiwilligen gepflegt. TVRage bietet ebenfalls eine XML-API, über die Metadaten zu Serien und Episoden abgefragt werden können. Die Endpunkte von TVRage sind ähnlich zu denen von TheTVDB, verwenden aber unterschiedliche URL-Strukturen und Feld-Bezeichnungen.

Die Daten von TVRage beinhalten vor allem aber neben dem Feld airtime (welches zudem das 24-Stunden-Format für Uhrzeiten verwendet) auch noch das Feld timezone, welches Zeitzonen in Repräsentationen wie "GMT-5 +DST" beinhaltet.

An TVRage werden die identischen Anfragen gestellt wie an TheTVDB (mit Angepassten URLs und Parametern), sodass nun pro Serie zwei Datensätze zur Verfügung stehen⁹. Da die Daten von TVRage keine Beschreibungen beinhalten¹⁰ und die weiteren Informationen identisch sein sollten, werden nur die Informationen zum Ausstrahlungs-Zeitpunkt von TVRage übernommen.

3.6.5 Aktualisieren von Serien

Beim initialen Hinzufügen von Serien werden diese anhand ihres Namens gesucht. Das Aktualisieren von Serien kann diesen Schritt überspringen, da mit jedem Serien-Eintrag in der Datenbank ebenfalls die IDs von TheTVDB und TVRage gespeichert werden.

Dazu werden zugehörige Episoden anhand von Staffel und Nummer eideutig identifiziert und können so auch aktualisiert werden.

Im derzeitigen Stadium werden alle Serien aktualisiert. Eine mögliche Verbesserung wäre, nur dann neue Daten abzufragen, wenn Aktualisierungen am wahrscheinlichsten oder am relevantesten sind. Das könnte für laufende Serien beispielsweise am Tag vor dem Ausstrahlen neuer Episoden sein. Außerdem könnte für beendete Serien ein sehr viel geringerer Rhythmus gewählt werden.

3.6.6 Import automatisiert testen

Wie die restliche Anwendung auch, soll der Import von Serien testbar sein, um Regressionen zu vermeiden. Da der Import jedoch von externen Diensten abhängt, gibt es hier einige zusätzliche Problemquellen. Die Dienste könnten offline sein, die Struktur ihre Antworten ändern oder auch abgeschaltet werden.

3.7.1 Motivation: Auflisten von zukünftig relevanten Episoden

Als Benutzer möchte ich es möglichst einfach haben, die Episoden zu finden, die ich bewerten möchte. Meist sind das genau die Episoden, die auf die zuvor von mir bewerteten folgen.

Daher ist eine sehr wichtige Funktion für ein Interface zu EpisodeFever das Auflisten der von einem Benutzer zuvor bewerteten Episoden sowie der darauf folgenden. Wurde zu einer Serie die 14. Episode der dritten Staffel bewerten, sollen z.b. die Episoden 14 bis 19 angezeigt werden. (Es ist zusätzlich zu beachten, dass nur Episoden bewerten werden können, die bereits ausgestrahlt wurden.)

3.7.2 Zuletzt bewertete Serien abfragen

Um an die zuvor beschriebenen Daten zu gelagen, wird zunächst eine Liste mit den zuletzt abgegebenen Bewertungen benötigt, gruppiert nach Serie. Eine passende SQL-Abfrage lässt sich wie folgt formulieren:

SELECT *
  FROM (
    SELECT
      ROW_NUMBER() OVER (
        PARTITION BY
          show_id
        ORDER BY
          updated_at DESC NULLS LAST,
          id DESC NULLS LAST
      ) AS row_number,
      t.*
    FROM
      votes AS t
    WHERE
      user_id = ?
  ) AS latest_votes
  WHERE "latest_votes"."row_number" <= ?
  LIMIT ?

Die Parameter für diese Abfrage (im Code als ? gekennzeichnet) sind die Benutzer-ID und die Anzahl der abzufragenden Bewertungen.

Hat man durch diese Abfrage nun eine Liste mit Bewertungen, lassen sich über die darin referenzierten Episoden- und Serien-IDs einfach die weiteren Episoden abfragen, indem man Episoden nach der Serien filtert, nach Staffel und Nummer sortiert und dann nur die ausgibt, welche auf die zuletzt bewertete folgen.

3.8.1 Anforderungen an die Suche

Die Überlegung die wir uns dazu gemacht haben waren folgende: Es gibt 3 Arten von Benutzern:

1. Der Benutzer weiß genau was er sucht. Er will etwas in die Suche eingeben, das richtige Ergebnis zurückbekommen und schnell auf die Daten zugreifen.

   Beispiel: Der Benutzer will eine Bewertung zu seiner Lieblingsserie abgeben und will möglichst schnell auf die entsprechende Seite geleitet werden. Er gibt den Titel der Serie in die Suchleiste ein und gelangt zur Serie.

2. Der Benutzer hat wenig Informationen und möchte, dass ihm dementsprechend Vorschläge gemacht werden, die am ehesten seiner Informationen entsprechen.

   Beispiel: Der Benutzer hat 5 Minuten einer ihm unbekannten Serie/Episode geschaut und weiß deshalb nur die Namen von 1-2 Charakteren oder nur einen Teil der Hintergründe, aber nicht den Titel der Serie/Episode. Er tippt was er weiß ein und bekommt nach Relevanz sortierte Vorschläge.

3. Der Benutzer hat keine Informationen und sucht nichts spezifisches. Er wird die Suchfunktion deshalb nicht benutzen und sich höchstens umschauen, welche Serien es gibt, bzw. welche Bewertungen diese haben.

Da der dritte Benutzertyp für die Suchfunktion keine Rolle spielt sind nur die Anforderungen der ersten beiden Benutzer wichtig.

Die Anforderungen an die Suchfunktion sind somit zusammengefasst: Schnelligkeit, richtige Ergebnisse bei präzisen Anfragen und nach Relevanz sortierte Vorschläge bei unpräzisen Anfragen.

3.8.2 Die Queries

Im wesentlichen besteht die Suche aus 2 SQL Anfragen, der Rechtschreibkorrektur und der Suche nach der Episode oder der Serie, wobei die Rechtschreibkorrektur vor der Suche nach den Serien/Episoden stattfindet. Weshalb dies so umgesetzt wurde, wird im Kapitel Idee und Umsetzung erläutert.

3.8.3 Suche nach Episoden

SELECT
    shows.name AS show,
    episodes.name AS episode,
    episodes.season, episodes.number, episodes.id, episodes.show_id
  FROM episodes JOIN shows ON shows.id = episodes.show_id
  WHERE
      to_tsvector('english_nostop', coalesce(episodes.name, '')) ||
      to_tsvector('english', coalesce(episodes.description, '')) @@
      to_tsquery(input)
  ORDER BY
      ts_rank((
        setweight(to_tsvector('english_nostop',coalesce(episodes.name,'')),'A') ||
        setweight(to_tsvector('english',coalesce(episodes.description,'')),'B')),
        to_tsquery('english_nostop', input)) DESC

Wie man sieht wird der Name, die Season, die Episodennummer, sowie der Name und die ID der Serie zurückgegeben. Dafür werden die Tabellen episodes und shows gejoint. Der interessante Teil ist der WHERE und ORDER BY-Teil, denn dabei werden die Features der PostgreSQL-Volltextsuche in Anspruch genommen:

to_tsvector([ config regconfig , ] document text) reduziert Text zu einem tsvector, der die Lexeme und deren Position innerhalb des Textes enthält. Ein Lexem ist die Einheit des Wortschatzes, die die begriffliche Bedeutung trägt [50].

to_tsquery([ config regconfig , ] query text) normalisiert Wörter und wird zum durchsuchen des ts_vector benutzt.

setweight(tsvector, "char") Gibt den Lexemen des tsvectors Gewichtungen. Char ist dabei A,B,C oder D, mit A höchstes und D niedrigstes Gewicht.

ts_rank([ weights float4[], ] vector tsvector, query tsquery [, normalization integer ]) gibt dem Query einen Rang.

Der @@ Operator überprüft, ob tsvector und tsquery übereinstimmen und liefert true oder false.

(Beispiele aus PostgreSQL Dokumentation zu Text Search Functions.)

Die Episoden-Namen und -Beschreibungen werden zu tsvector umgewandelt, gewichtet und mit tsquery untersucht. Was besonders ins Auge fällt, ist dass für die Beschreibungen die Sprache english und für die Titel english_nostop verwendet wurde. Die Sprache english_nostop wurde von uns angelegt und der Unterschied zu english besteht darin, dass Stop Wörter nicht entfernt werden. Dies ist besonders wichtig, da Titel durchaus Stop Wörter enthalten können.

Beispiel: Wenn man die Serie Doctor Who sucht und in die Suche who eingibt würde, die Suche die Serie nicht finden, weil who ein Stop Wort ist.

Die Ergebnisse der Suche werden abschließend nach Relevanz absteigend sortiert, sodass das Ergebnis mit dem höchsten Rang als erstes ausgegeben wird.

SELECT word
  FROM unique_lexeme
  WHERE word % input AND similarity(word, input) >= 0.5
  ORDER BY similarity(word,input) DESC
  LIMIT 1;

3.8.4 Such-Indizes

Um die Laufzeit der SQL-Abfragen drastisch zu verringern, stellt PostgreSQL sogenannte Indizes zur Verfügung. Diese sind sozusagen eine Verknüpfung oder eine Art Lesezeichen, auf die bei der Indexerstellung definierte Spalte einer Tabelle.

Dabei gibt es 2 Arten von Indizes: Den GIN und GiST Index.

As a rule of thumb, GIN indexes are best for static data because lookups are faster. For dynamic data, GiST indexes are faster to update. Specifically, GiST indexes are very good for dynamic data and fast if the number of unique words (lexemes) is under 100,000, while GIN indexes will handle 100,000+ lexemes better but are slower to update.

– PostgreSQL Dokumentation zu Full Text Search

Da die Serien- und Episoden-Daten zum größten Teil statisch sind, eine niedrige Laufzeit der Queries für uns wichtig ist und die GiST Indizes auch falsche Ergebnisse liefern können, haben wir entschieden, die GIN-Indizes sowohl für die Suche nach Serien/Episoden, als auch für die Rechtschreibkorrektur zu verwenden.

3.8.5 Idee und Umsetzung

In diesem Abschnitt behandeln wir unsere Idee für die Suche und deren Umsetzung.

Die Überlegung war es, dass wir im Frontend eine Library benutzen, welche es uns ermöglicht, die Suchanfragen periodisch bzw. live, also während der Benutzer noch eintippt, zu senden.

Wir haben uns mehrere Librarys angeschaut, unter anderem typeahead.js [51] und rx.js [52], haben uns aber letztendlich für kefir.js [53] entschieden, da dieses sehr kompakt und besonders performant ist. Wie rx.js bietet kefir.js eine Implementierung von Event-Streams und ermöglicht durch zahlreiche Hilfsmethoden effiziente, funktional reaktive Programmierung [54].

Im wesentlichen sieht das Skript für das Autocompletion-Feature wie folgt aus:

var queries = Kefir.fromEvent(inputField, 'keyup')
  .debounce(250)
  .map(function (ev) { return ev.target.value; })
  .filter(function (val) { return val.length > 0; })
  .skipDuplicates()
  .onValue(function (ev) { /* trigger http request for search */ });

Tippt der Benutzer tippt etwas ein, wird die Suchanfrage als GET-Request gesendet und das eingegebene Wort wird mit den Lexemen aus der Materialized View unique_lexeme verglichen. Dabei wird das Lexem mit der größten Ähnlichkeit ausgewählt und dieses an die Suche nach der Serie/Episode als Parameter übergeben. Anschließend werden die Ergebnisse nach Relevanz sortiert zurückgegeben.

Auf diese Weise haben wir somit alle unsere Anforderungen an die Suche erfüllt: Schnelligkeit, richtige Ergebnisse bei präzisen Anfragen und nach Relevanz sortierte Vorschläge bei unpräzisen Anfragen.

3.8.6 Beispiel für eine Suche

Wir wollen Mike, den Namen des Protagonisten aus der Serie Suits in die Suche eingeben und ebendiese Serie zurückbekommen.

Wir tippen also m ein, der GET-Request wird abgeschickt, die Fehlerkorrektur bestimmt das Lexem das die höchste Bewertung für m hat z.B. mia, übergibt es an die Suche und liefert alle relevanten Ergebnisse.

Während die Suche durchgeführt wird, tippen wir aber weiter, sodass wir mik in der Suchleiste stehen haben.

Der GET-Request wird erneut abgeschickt, die Fehlerkorrektur bestimmt, dass das Lexem mit der höchsten Bewertung für mik, mike ist und gibt es an die Suche weiter. Diese gibt uns wieder alle relevanten Ergebnisse zurück. In diesem Beispiel gehen wir davon aus, dass eine andere Serie relevanter ist. Deshalb präzisieren wir unsere Suche und tippen ein mike suit. GET-Request wird abgeschickt, da mike und suit 2 Wörter sind die durch ein Leerzeichen getrennt sind, aber wir nur 1 Wort an die Fehlerkorrektur übergeben können, wird der Input getrennt und ein Array erzeugt. Zuvor wird die Eingabe jedoch bei jeder Suchanfrage normalisiert. Dafür werden unter anderem Leer- und Sonderzeichen durch + ersetzt, sodass immer eine gültige Suchanfrage vorliegt.

function normalize(word) {
    var word = word.toLowerCase()
    .replace("%20","+")
    .replace(/([+])+/g,"+")
    .match(/([A-Za-z0-9+])+/g);
  
    if ((word === undefined) || (word === '') || (word === null)) {
      throw new E.BadRequestError("Please enter a valid search query!");
    } else {
      return word.join("+");
    }
  }

Dann wird die normalisierte Eingabe getrennt und ein Array erzeugt. Das Array wird dann an die Rechtschreibkorrektur übergeben, diese gibt für suit, suits zurück.

mike und suits werden dann zusammengefügt und durch das Zeichen für ein logisches Und getrennt:

Promise.all(
    input.split('+').map(function (word) { return spellcheck(word); })
  )
  .then(function (words) {
    var query;
    input = words
    .filter(function (word) { return word && word[0]; })
    .map(function (word) { return word[0].word; })
    .join('&');
    // ...
  });

Als Input wird nun "mike&suits" an die Suche übergeben und wir bekommen als relevantestes Ergebnis die Serie Suits.

4.1.1 Technologie-Entscheidungen

Zwei Entscheidungen zu Modulen, die wir einsetzen wollten, haben wir revidiert.

Zu Beginn war geplant, die Benutzer-Authentifizierung auf Basis von Passport [34] zu implementieren. Dieses Modul ist im Grunde jedoch nur eine Sammlung von Adaptern verschiedener Authentifizierungsmethoden, um Benutzer z.B. über deren vorhandene Facebook-, Twitter- und OpenID-Accounts zu registrieren. Das Modul für eine lokale Benutzerverwaltung, passport-local ist ein recht einfacher Adapter, welcher jedoch verlangt, dass die Repräsentation des Benutzers in der Datenbank (Auslesen und Ändern) selbst geschrieben wird. Da dies das mit Abstand komplexeste Unterfangen der Benutzer-Authentifizierung ist und passport-local sonst kaum Funktionen mitbringt, haben wir uns entschieden ganz darauf zu verzichten und den gesamten Workflow selbst zu implementieren. Hätten wir MongoDB verwendet, wäre es jedoch möglich gewesen, passort-local-mongo zu verwenden, welches Session-Handling und das Benutzer-Schema für diese Datenbank implementiert.

Ein weiteres Modul, welches wir letztendlich nicht verwendet haben, ist node-tvdb [55], eine Implementierung der TheTVDB-API. Dieses Modul ließ sich schnell durch die direkte Verwendung von xml2js [43] und superagent [29] ersetzen. Dies hat den zusätzlichen Vorteil, dass auf die selbe Weise auch die Schnittstelle zur TVRage-API geschrieben werden konnte.

4.1.2 Zu node.js und der Zukunft von JavaScript

Das ursprüngliche Vorhaben für das Projekt war, eine Applikation auf Basis von node.js zu entwickeln. Abschließend sind wir zufrieden mit dieser Wahl. Node ist zwar noch nicht als 1.0-Version erschienen, da es aber von einigen großen Unternehmen bereits für wichtige Projekte verwendet wird, sind große Teile von Node dennoch als stabil und gut getestet einzustufen. Es werden eine Reihe aktueller (wie auch älterer Versionen) regelmäßig mit Sicherheits-Aktualisierungen versehen und viele APIs der Kern-Module sind als stabil markiert.

Dass node trotz seinem Fokus auf Asynchronität auf dem Ausführen von JavaScript basiert, bedeutet zur Zeit, dass viele Programmier-Techniken zur Abstraktion und Verbesserung der Ergonomie nur als Module verfügbar sind, die Sprache selbst diesen aber agnostisch gegenüber ist. Auch, wenn sich dies mit einer zukünftigen Version von node ändern sollte (z.B. durch die Unterstützung neuer Funktionen aus dem ECMAScript 2015-Standard [56]), wird es noch viele Module geben, die diese Techniken nicht verwenden, sowie andere, welche ähnliche, aber inkompatible oder obsolete Implementierungen einsetzen.

Ein Beispiel hierfür ist die von uns verwendete Bibliothek bluebird [20], um Promises abzubilden. Unsere Wahl fiel explizit auf diese Bibliothek, da sie verspricht, kompatibel zu den nativen Promises in ECMAScript 2015 zu sein. Dass andere von uns verwendeten Module wie knex und bookshelf ebenfalls bluebird als Abhängigkeit haben, war ein ziemlich Glücksgriff. Aus anderen Projekten war bekannt, dass es sonst nötig gewesen wäre, an vielen Stellen Promise-Instanzen der einen in Promise-Instanzen der anderen Bibliothek zu konvertieren, was weder für Performance noch für Entwickler-Effizient gut ist.

Sobald node in einer stabilen Version einen Großteil der Funktionen von ECMAScript 2015 (und nachfolgenden Revisionen) unterstützt, wird es möglich sein, einige andere Pattern zu verwenden, um Applikationen auf eine andere Weise zu implementieren. Konkret existiert beispielsweise mit koa.js [11] schon eine Alternative zu express.js [8], welche Middlewares auf Basis von Generatoren¹⁴ implementiert.

Die Grenzen von JavaScript sind auch an anderen Stellen zu sehen. Gerade für größere Projekte kann es problematisch sein, Interfaces korrekt zu definieren und zuversichtlich verwenden zu können, da JavaScript als dynamische Sprache hier von sich aus kaum Sicherheiten bietet. Abhilfe schaffen hier Ansätze wie statische Code-Überprüfung (z.B. mit ESLint [57]) oder auf JavaScript aufsetzende Type Systeme wie TypeScript [58] oder Flow [59].

Bei der Entwicklung EpisodeFever konnten wir mit den Nachteilen von Node und JavaScript gut umgehen und die Vorteile – eine einfach zu lernende Sprache und ein großen Ökosystem von Modulen – erfolgreich ausnutzen. Für ähnliche Projekte, gerade für kleinere Webserver, würden wir es wieder verwenden.

4.2.1 Zeitpunkte für Daten-Aktualisierung

Mit steigender Anzahl von Serien in der Datenbank wird das Aktualisieren der Daten und damit auch das Laden neuer Episoden über die APIs immer länger dauern. Aktuell existiere nur die Möglichkeit, alle Serien-Daten zu aktualisieren.

Eine Verbesserungs-Möglichkeit wäre, ein Scheduling-System zu verwenden, indem einzelne Serien zu bestimmten Zeitpunkten aktualisiert werden. Während laufende Serien so z.B. einmal pro Woche (etwa zwei Tage vor dem Ausstrahlen einer neuen Episode) aktualisiert werden, könnten beendete Serien weniger häufig aktualisiert werden, da sich diese Daten mit hoher Wahrscheinlichkeit nicht mehr ändern werden.

4.2.2 Durchschnitts-Bewertungen speichern

Aktuell werden Durchschnitts-Bewertungen immer dynamisch berechnet. Für Serien ist dies jedoch mit steigender Anzahl Bewertung recht zeitaufwendig, da immer alle Bewertungs-Einträge gelesen werden müssen. Würde man diese Durchschnitt beim Anlegen bzw. Aktualisieren einer Bewertung berechnen und in der Serie oder Episode speichern, könnte diese Zeit sparen. (Es wird angenommen, dass die Serien bzw. Episoden und deren Durchschnitte häufiger abgefragt werden als Bewertungen gespeichert werden.)

Dies könnte entweder in der node-Anwendung beim Speichern einer Bewertung oder aber in der Postgres-Datenbank über Trigger realisiert werden.

4.2.3 Empfehlungen basierend auf bisherigen Bewertungen

Als Benutzer von EpisodeFever möchte ich nicht nur mir bekannte Serien bewerten, sondern auch neue entdecken. Ein bekannter und hilfreicher Mechanismus dazu ist das Darstellen von Empfehlungen, welche auf Basis von den von mir und den von anderen Benutzern abgegebenen Bewertungen.

Viele Algorithmen zum Bestimmen von Empfehlungen beziehen sich auf den E-Commerce-Markt, bei dem es darum geht, Benutzern Produkte zu empfehlen, die sie vielleicht auch kaufen wollen. Häufig sind die einzigen Metriken dazu positive Ereignisse, z.B. Benutzer A hat Produkt X angesehen oder Benutzer A kaufte Produkt X.

Die von EpisodeFever erfassten Bewertungen bieten dabei detailliertere Informationen. Sie bilden dabei nicht nur die Relation Benutzer A mag Episode X (und darüber transitiv auch Benutzer A mag Serie Z) ab, sondern auch Benutzer gefällt Episode B nicht bzw. Benutzer ist Episode C gegenüber indifferent. Ein möglicher Empfehlungs-Mechanismus muss auch diese Zu- oder Abneigung verarbeiten, um alle Informationen auszunutzen und möglichst genau zu arbeiten.

4.2.4 Benutzern das explizite Verwalten von betrachteten Serien erlauben

In der aktuellen Form der Anwendung werden die Relationen zwischen Benutzern und Serien nur implizit über die abgegebenen Bewertungen gesetzt. Wurde eine Serie bewertet, so wird angenommen, dass der Benutzer sie schaut.

Dies hat jedoch zwei Schwachstellen:

1. Der Benutzer kann keine Serie explizit entfernen, sodass sie nicht mehr in seiner Liste zukünftiger Episoden auftaucht.
2. Es können keine Serien vorgemerkt werden, welche zwar schon angekündigt wurden, wo aber noch keine Episode ausgestrahlt wurde.

Möglicher Lösungsansatz wäre hier, eine neue Relation Watch¹⁵ hinzuzufügen. In dieser wird bei der ersten Bewertung automatisch ein Eintrag mit Benutzer- und Serien-ID erzeugt. Zusätzlich wird dem Benutzer aber auch ermöglicht, selbst diese Relation zu erzeugen, eine Liste mit Watches einzusehen und Einträge daraus zu entfernen.

4.2.5 Server-Infrastruktur

Um die entwickelte Software betreiben zu können, wird (mindestens) ein korrekt konfigurierter Server benötigt, auf welchen die node-Anwendung sowie Postgres ausgeführt wird. Dies ist bereits nötig, um die Software entwickeln und testen zu können. Die Hardware-Anforderungen für einen solchen Server sind im Vergleich zu existierenden Angeboten[^vserver-preise] nicht besonders hoch; Die node-Anwendung braucht auf dem Entwicklungssystem etwa 36MB RAM und minmal CPU-Leistung. Da die in der Postgres-Datenbank gespeicherten Daten ebenfalls nicht sehr groß sind, sollte es möglich sein, auf einem Server mit 2GB RAM die gesamte Datenbank im Hauptspeicher zu halten.

Um statische Dateien performant auszuliefern (z.B. Grafiken) und komprimierte Verbindungen sowie verschlüsselte Protokolle wie HTTPS und HTTP2 verwenden, sollte zudem ein Web-Server wie nginx als Reverse Proxy verwendet werden, welcher im vor der node-Anwendung liegt und an diese die relevanten HTTP-Anfragen weitergibt.

Es ist zu bedenken, dass Anwendungen auf Basis von node standardmäßig zwar asynchronen Kontrollfluss verwenden, jedoch JavaScript nur in einem Thread ausführen. Auf diese Weise kann der JavaScript-Teil einer node-Anwendung keinen Gebrauch von Mehrprozessor-Systemen machen. Eine recht einfache Lösung dafür ist es, die Anwendung in einem Cluster zu verwenden. Dabei startet ein Master-Prozess die Anwendung in einer beliebigen Anzahl von Kind-Prozessen und gibt Netzwerk-Anfragen an diese weiter.

Cluster ist ein mit node mitgeliefertes Modul. Es ist jedoch von Vorteil, auf einen komplexeres Tool wie PM2 zurückzugreifen. Dieses kann nicht nur mehrere Anwendungen ohne Code-Änderungen als Cluster starten, sondern stellt auch fest, wenn diese abstürzen und kann sie dann neu starten. Des Weiteren bietet es einige Möglichkeiten, Log-Ausgaben mitzuschreiben und CPU- und Speicher-Auslastung pro Prozess einzusehen.

4.2.6 Analyse von Protokoll-Daten

Die Server-Anwendung schreibt Informationen zu jeder gesendeten HTTP-Antwort sowie zu jeder SQL-Abfrage auf stdout (d.h., das Terminal, wenn die Anwendung im Vordergrund läuft, ansonsten das System-Log). Die Protokoll-Daten beinhalten einen Zeitstempel, Art der Anfrage, de Rückgabewert (Fehler-Code) und wie lange der Server brauchte, um die Anfrage zu bearbeiten. Diese Daten müssen im aktuellen Zustand von einem Entwickler oder Administrator persönlich ausgewertet werden, was das Auffinden von Fehlern von Geschwindigkeits-Problemen erschwert.

Um diese Daten analysieren und darstellen zu können, gibt es passende Software, welche teilweise unter einer Open-Source-Lizenz (vgl. [2]) verfügbar ist. Ein Beispiel hierfür ist die Kombination aus Logstash, Elasticsearch und Kibana (ELK, [60]).

Mit einer angepassten Konfiguration sollte es möglich sein, die Protokolle der EpisodeFever-Anwendung mit Logstash einlesen zu lassen und die Daten in eine Elasticsearch-Datenbank zu schreiben. Mit Kibana lassen sich diese dann grafisch darstellen, filtern und auswerten.