Erweiterung schreiben

Einleitung

Bei Erweiterungen handelt es sich um Python-Skripts, die auf den weltweiten Edges von WaveCDN ausgeführt werden. Damit ist es möglich, die Abarbeitung der Webuser-Anfragen stark zu beeinflussen. Die Erweiterungen können Daten auslesen und verändern. Erweiterungen erlauben es WaveCDN auf flexibelste Art und Weise an die eigenen Anforderungen anzupassen.

Die Erweiterungen laufen auf den Edges in abgeschlossenen Einheiten. Ein Python-Programm lädt die Erweiterung und führt die Erweiterungsfunktionen in mehrerenen Python-Threads parallel aus. Die Funktionen müssen also thread-safe sein. Der Speicher ist auf insgesamt 8 MB limitiert und die CPU-Nutzung ist ebenfalls stark eingeschränkt. Aufgrund der begrenzten Ressourcen sollten ausschließlich Python-Skripts mit hoher Performance eingesetzt werden. Für Fehler oder Beschränkungen bei der Ausführung von Erweiterungen übernehmen wir keinerlei Verantwortung. Man sollte Erweiterungen insbesondere ausgiebig testen.

Wir empfehlen vorweg die FAQ durchlesen.

Funktionen

Wenn ein Webuser eine Anfrage an WaveCDN stellt, so müssen bis zur Antwort einige Schritte abgearbeitet werden. Diese sind im Anfragenmodell beschrieben. Konkret handelt es sich um folgende sechs Schritte:

• wavecdn_receive
• wavecdn_hit
• wavecdn_miss
• wavecdn_pass
• wavecdn_fetch
• wavecdn_deliver

Eine Erweiterung kann sich in die einzelnen Schritte einklinken, in dem sie eine Python-Funktion mit dem jeweiligen Schrittnamen deklariert. Damit zum Beispiel eine Erweiterung im Schritt wavecdn_receive ausgeführt wird, muss die entsprechende Funktion im Python-Skript deklariert sein. Das kann wie folgt aussehen:

#!/usr/bin/python

def wavecdn_receive():
    pass

Parameter

Bei Aufruf einer Funktion der Erweiterung wird genau ein Parameter übergeben. Es handelt sich dabei um eine Instanz der Environment-Klasse. Aus dem Environment können Daten ausgelesen oder auch gespeichert werden. Über das Environment ist es also möglich die Abarbeitung der Anfrage zu beeinflussen.

Um ein Gefühl dafür zu bekommen, was alles möglich ist, sollte man sich die Dokumentation der Environment-Klasse anschauen.

Rückgabewerte

Die Erweiterungsfunktionen können bestimmte Werte zurückgeben. Je nach Schritt gibt es bestimmte Rückgabewerte, mehr dazu später.

Deployment

Um die Erweiterungen auf den weltweiten Edges von WaveCDN zu deployen, muss man zunächst im Webpanel das CDN-Setup öffnen, in welchem die Erweiterung laufen soll. Im Tab "Erweiterungen" gibt es einen Button zum Hinzufügen einer Erweiterung. Nach Einfügen des Python-Codes und Abschicken des Formulars wird die Erweiterung weltweit installiert. Dies kann einige Minuten dauern. Wenn die Erweiterung Ressourcen betrifft, die im Cache von WaveCDN liegen, ist eine Invalidierung erforderlich.

Snippets

Wir wollen nun einige häufig verwendete Snippets auflisten.

Cookie-Header aus Webuser-Anfrage entfernen

Die Folgende Erweiterung entfernt bei Eintreffen der Webuser-Anfrage den Cookie-Header. Der Code wird häufig benötigt, wenn man bestimmte Pfade cachbar machen will und deshalb den Cookie entfernen muss. Siehe auch die <Caching-Voraussetzungen>.

#!/usr/bin/python

def wavecdn_receive(env):
    env.unset_request_header('Cookie')

Set-Cookie-Header aus der Backend-Antwort entfernen

Wenn eine Ressource gecached werden soll, müssen die Caching-Voraussetzungen erfüllt sein. Dazu gehört, dass in der Antwort vom Backend kein Set-Cookie-Header vorhanden ist. Mit dem folgenden Snippet lässt sich der Set-Cookie-Header aus der Antwort vom Backend entfernen.

#!/usr/bin/python

def wavecdn_fetch(env):
    env.unset_backend_response_header('Set-Cookie')

Webuser-Anfrage mit Cookie cachbar machen

Wenn Anfragen gecached werden sollen, müssen die Caching-Voraussetzungen erfüllt sein. Dazu gehört, dass in der Webuser-Anfrage kein Cookie vorhanden ist oder dass "Cache with Cookies" aktiviert ist. Im folgenden sollen Anfragen mit Cookies explizit gecached werden. Dafür aktivieren "Cache with Cookies".

#!/usr/bin/python

def wavecdn_receive(env):
    env.set_cache_with_cookies(True)

URL umschreiben

Ferner ist es möglich mit einer Erweiterung die angefragte URL umzuschreiben.

#!/usr/bin/python

def wavecdn_receive(env):
    env.set_request_uri('/rewritten-url')

Freie Erweiterung

Sowohl das WaveCDN Team als auch die Community haben im Laufe der Zeit zahlreiche Erweiterungen geschrieben, die frei zur Verfügung stehen.

Troubleshooting

Zunächst sollte ein Blick in die Logs geworfen werden. Dafür klickt man auf das betroffene CDN-Setup, auf den Tab "Erweiterungen" und auf den Button "Anzeigen" bei der entsprechenden Erweiterung. Unten auf der Seite sind dann die letzten Log Messages vorzufinden. Liegt es ggf. am Caching? Wurde das CDN-Setup invalidiert?