Velog-API zur Anzeige von Aufrufzahlen (Beta)

Entwicklungshintergrund und Implementierungsidee

• Ich wollte die Aufrufzahlen meiner auf Velog veröffentlichten Beiträge sehen, aber mich dafür jedes Mal einzuloggen, war lästig
• Man könnte die interne View-API von Velog reverse engineeren, aber das wäre umständlich und wenig erweiterbar (z. B. für Besucherbenachrichtigungen)
• Ich erinnerte mich daran, dass frühere koreanische Mail-Dienste Lesebestätigungen über Pixelbilder bereitgestellt haben
• Velog unterstützt das Schreiben von Beiträgen mit Markdown-Syntax
• Browser blockieren einfache Bildaufrufe auch bei Cross-Site-Domains nicht
• Wenn man in einen Beitrag ein transparentes 1x1-Pixel-Bild einfügt, kann der Server bei jedem Aufruf des Beitrags einen Abruf protokollieren
• Die meisten Velog-Nutzer haben nicht mehr als 1.000 Besucher pro Tag pro Beitrag. Für dieses Traffic-Niveau reicht Workers KV aus
• Das ist nicht auf Velog beschränkt, sondern funktioniert auf jeder Plattform, die das Einfügen von Bildern per Markdown unterstützt (und Bilder von einer benutzerdefinierten Domain ausliefern kann)

Funktionsweise

• Dem Bild wird ein Identifikationswert (slug) zugewiesen. Die Antwort wird nicht über ein CDN, sondern über programmierbare Workers bereitgestellt. Wenn der Identifikationswert als Key prefix in KV verwendet wird, um Abrufprotokolle zu speichern, lassen sich Page Views einfach ermitteln
• Wenn Datum, IP, userAgent und Bild-Identifikationswert mit einer Hash-Funktion zu einem Key verarbeitet werden, ist zumindest eine minimale Erkennung doppelter Besuche möglich
  • HASH: 128-Bit-Hash auf Basis von SHA-256, kodiert als base64url (22 Zeichen).
  • KEY: view:${slug}:${hash}.
  • VALUE: UserAgent, Date...
• Der kostenlose Workers-KV-Plan unterstützt 1.000 PUT- und LIST-Operationen pro Tag.
  • PUT: Es können pro Tag 1.000 Besucherzählungsdaten gespeichert werden
  • LIST: Es können pro Tag mehr als 1.000 Page-View-Informationen bereitgestellt werden
• Für Anfragen zum Abrufen von Page Views wird der LIST-Befehl verwendet. Dabei werden die Daten über den prefix des Identifikationswerts (slug) geladen und anschließend einfach gezählt
  • Da das Abrufen von Page Views keine hohe Echtzeit-Anforderung hat, können mit geeignetem Caching der Antwortwerte auch mehr als 1.000 Anfragen pro Tag verarbeitet werden

Grenzen

Da für eine schnelle Entwicklung ein einfacher Speicher wie KV verwendet wurde, gibt es folgende Einschränkungen.

• Eventual consistency: Workers-KV-PUT-Anfragen sind nicht in Echtzeit. Wenn Echtzeit zwingend erforderlich ist, sollte Durable Objects(DO) verwendet werden.
• LIST-Abhängigkeit: Das Zählverfahren über den LIST-Befehl wird mit der Zeit langsamer, weil immer mehr KEY-Werte geladen werden müssen (unter der Annahme, dass kontinuierlich Page Views anfallen). Man sollte die Speicherstruktur per Cron-Job fortlaufend aktualisieren oder den Einsatz von DO bzw. Analytics Engine in Betracht ziehen.

Geplante Unterstützung

Die folgenden Funktionen sollen so bald wie möglich ergänzt werden.

• Sortierung nach Datum: Mit Unix Time, derselben Methode, die in Serverless Blog-Kommentar-API in 30 Minuten bauen für die Sortierung neuester Kommentare verwendet wurde, lässt sich eine nach den neuesten Sitzungen sortierte Liste bereitstellen
• API-Sicherheit: Geplant über zusätzliche Middleware. Vorgesehen ist die Nutzung des HTTP-Authorization-Headers
• Rate Limit: Bei populären Velog-Nutzern könnten von Timing und Neid getriebene Nutzer bösartige Anfragen senden, daher ist eine Gegenmaßnahme nötig. Vermutlich wird das bei mir selbst kein Thema sein und deshalb als Letztes ergänzt...
• Suche: Soll über zusätzliche APIs unterstützt werden
  • Datum: Suche nach bestimmten Tagen oder Zeiträumen. Dafür ist eine Änderung der KEY-Struktur nötig
  • Sitzung: Suche nach Aktivitätsinformationen einer bestimmten Sitzung. Aktuell sind Sitzungsinformationen für jeden Beitrag einen Tag lang gültig. Eine Prüfung der Datenschutzrichtlinie ist erforderlich
  • Browser/OS: Soll auf Basis der aus dem UserAgent geparsten Informationen bereitgestellt werden. Auch wenn es nicht besonders präzise ist, ermöglicht es zumindest eine grobe Einordnung
• Service-API: Die API soll als Dienst bereitgestellt werden, damit sie jeder einfach per E-Mail-Verifizierung + Ausgabe eines privaten Schlüssels nutzen kann
  • Webhook: Bei Auftreten eines Page-View-Ereignisses wird eine POST-Anfrage bereitgestellt. Dadurch werden Benachrichtigungen über das von Entwicklern geschätzte Slack möglich
  • E-Mail: Eine klassische, aber praktische Benachrichtigungsfunktion für Nutzer, denen Webhook-Verarbeitung zu lästig ist
  • Custom campaign: Bereitstellung eines integrierten Bild-Identifikationswerts (slug) für konfigurierte Ereignisse (z. B. Erreichen einer bestimmten Aufrufzahl)

Ergänzung

• Wer sich für die interne Funktionsweise interessiert, findet Details in Entwicklungsbericht zur Velog-API für Aufrufzahlen, beginnend mit 1x1 Pixel.
• Installations- und Deployment-Methoden, ausführliche API-Referenz und der vollständige Code sind im Github-Repository zu finden.