Seminar ActivityPub Server entwickeln: Referenz-Implementierung (Hands-on)

Lernziele

• Actor-Dokumente und Kernendpunkte implementieren (konzeptionell + praktisch)
• Inbox-Verarbeitung als Pipeline bauen (Parse, Validate, Store, Apply)
• Outbox und Zustellung über Queue realisieren
• Dedupe und Idempotenz durchgängig anwenden
• Interop-Probleme systematisch lokalisieren (Payload, Zustellung, State)

Inhalte und Module

• Projektstruktur: Komponenten, Adapter, Storage, Worker
• Actor-Endpunkte: Representation, Public Key Konzept (konzeptionell)
• Collections: followers/following, outbox pages
• Inbox: Validierung, Dedupe, Side Effects, Persistenz
• Outbox: Activity erzeugen, persistieren, Zustellung an Remote Inboxes
• Delivery Worker: Queue, Retries, Backoff, Dead-letter
• Interop: Payload-Normalisierung, tolerante Parser, Feature Flags

Agenda (UE-Plan)

Tag 1

• UE1: Referenzarchitektur und Projekt-Setup
• UE2: Domänenmodell und Storage-Schema
• UE3: Actor-Dokument erzeugen
• UE4: Collections Grundgerüst
• UE5: Outbox: lokale Create Activities
• UE6: Inbox: Parser und Persistenz
• UE7: Dedupe-Basics
• UE8: Review und Refactoring

Tag 2

• UE1: Follow/Accept State Machine
• UE2: followers/following Collections
• UE3: Threading (Replies) Grundlogik
• UE4: Update/Delete Handling
• UE5: Side Effects und Idempotenz
• UE6: Indexing und Query Patterns
• UE7: Teststrategie (Unit/Integration)
• UE8: Review

Tag 3

• UE1: Delivery Architektur (Queue/Worker)
• UE2: Target Inbox Resolution (konzeptionell)
• UE3: Retry/Backoff Implementationsmuster
• UE4: Rate Limiting und Backpressure
• UE5: Dead-letter und Replay
• UE6: Observability Hooks
• UE7: Lasttests (klein) und Metriken
• UE8: Review

Tag 4

• UE1: Interop Debugging Prozess
• UE2: Toleranzregeln und Normalisierung
• UE3: Feature Flags für Verhalten
• UE4: Moderationshooks (Vorbereitung auf S7)
• UE5: Security Hooks (Vorbereitung auf S6)
• UE6: Stabilisierung und Doku
• UE7: Mini-Abnahme gegen Checkliste
• UE8: Architektur-Readme finalisieren

Praxisübungen Schritt für Schritt

Übung A: Inbox-Verarbeitungspipeline

1. Eingangspunkt definieren: /inbox POST akzeptiert JSON.
2. Parser bauen: JSON lesen, Pflichtfelder prüfen (id/type/actor/object).
3. Validation Layer: Typenwhitelist, Größenlimits, schematische Checks.
4. Dedupe Check: activity.id gegen Inbox-Store.
5. Persistenz: Activity speichern, Object optional entkoppelt speichern.
6. Apply Layer: Side Effects (z. B. Follow-Status, Timeline Eintrag) nur einmal.
7. Response: idempotent 2xx, Fehler differenziert (4xx vs. 5xx).
8. Logging: correlationId, remoteActorId, activityId.

Übung B: Outbox → Delivery Queue

1. Outbox-POST nimmt lokale Aktion (Create/Follow) an.
2. Activity erzeugen: neue activity.id, object.id (falls neu).
3. Persistieren: Activity und Object in Storage.
4. Targets bestimmen: Empfänger aus to/cc ableiten, remote inbox URLs auflösen (konzeptionell).
5. Jobs erzeugen: pro Target ein Delivery-Job.
6. Worker verarbeitet Jobs: send, retry, mark delivered.
7. Fehlerhandling: 429 Backoff, 5xx retry, 4xx fail-fast mit Klassifikation.