Peer Sync – Concept

Status: CONCEPT · Erstellt April 2026 Übergeordnet: TOOL_chat_roadmap.md Verwandt: @xpulse/sync, COMP_event_concept-message-structure.md

Warum ein eigenes Konzept?

xPulse Chat ist P2P und serverless – Nachrichten werden nie auf einem Server gepuffert. Das bedeutet: wenn zwei Peers nicht gleichzeitig online sind, entstehen Lücken. Dieses Konzept legt fest wie diese Lücken geschlossen werden – ohne Server, ohne zentrale Autorität, robust und privacy-by-design.

Grundprinzip

Sync passiert ausschließlich P2P über den DataChannel, beim Verbindungsaufbau. Es gibt zwei unabhängige Sync-Typen – sie wissen nichts voneinander:

• Profile Sync – Profil-Daten (Display Name, Avatar, ...)
• Chat Sync – Nachrichtenverlauf

Beide werden durch syncer.sync() getriggert – von außen, z.B. beim Connect-Event. Der Syncer selbst entscheidet nie wann er läuft.

Message Format & Graveyard

Message-Struktur (v1), UI-Darstellung, Lösch-Modi, Graveyard und Migration v0 → v1 sind vollständig dokumentiert in:

→ TOOL_chat_concept-message.md

Für den Sync relevant:

• id – Basis für Duplikat-Check
• editedAt – Basis für Edit-Vergleich im Comparator
• v – Basis für Migration im Converter
• Graveyard (xp_graveyard_{chatId}) – Basis für Tombstone-Logik

@xpulse/sync – Package Struktur

Der Sync-Mechanismus ist als eigenständiges Package realisiert – analog zu @xpulse/cli: Infrastruktur bereitstellen, konkrete Implementierung bleibt beim Tool.

Abstrakte Basisklassen

1
@xpulse/sync
2
  Provider    – stellt Daten bereit (collect())
3
  Receiver    – empfängt Daten vom DataChannel (listen())
4
  Converter   – wandelt rohe Daten in internes Format um (convert())
5
  Comparator  – vergleicht eingehende mit lokalen Daten (compare())
6
  Syncer      – orchestriert die Pipeline (sync())

Kein gegenseitiges Wissen zwischen den Klassen – jede kennt nur ihre eigene Aufgabe. Der Syncer kennt nur die abstrakten Basisklassen.

Pipeline

1
Provider → [DataChannel] → Receiver → Converter → Comparator

• Provider sammelt lokale Daten und schickt sie über den DataChannel
• Receiver hört auf den DataChannel und empfängt rohe Daten
• Converter kennt das konkrete Eingangsformat und normalisiert es
• Comparator entscheidet was gemergt, ignoriert oder markiert wird

Provider und Receiver kennen sich nicht – der DataChannel ist der einzige Vertrag zwischen beiden Seiten. Jeder Peer ist gleichzeitig Provider und Receiver.

Trigger

1
// Syncer wird von außen getriggert – er entscheidet nie selbst
2
peerConnection.on('connected', () => chatSyncer.sync());
3
 
4
// oder via Cron (zukünftig)
5
cron.every('5m', () => chatSyncer.sync());

Konkrete Implementierung in xpulse-chat

Ordnerstruktur

1
xpulse-chat/src/syncer/
2
  profile/
3
    ProfileProvider.js
4
    ProfileReceiver.js
5
    ProfileConverter.js
6
    ProfileComparator.js
7
    ProfileSyncer.js
8
  chat/
9
    ChatProvider.js
10
    ChatReceiver.js
11
    ChatConverter.js
12
    ChatComparator.js
13
    ChatSyncer.js

Zukünftig:

1
  device/
2
    DeviceProvider.js
3
    ...
4
    DeviceSyncer.js

ChatSyncer Beispiel

1
class ChatSyncer extends Syncer {
2
  constructor() {
3
    super(
4
      new ChatProvider(),    // holt Nachrichten aus localStorage
5
      new ChatReceiver(),    // hört auf DataChannel
6
      new ChatConverter(),   // kennt das Chat Message Format + Migration
7
      new ChatComparator()   // mergt, prüft Graveyard, ignoriert Duplikate
8
    );
9
  }
10
 
11
  // atomar – eine einzelne Message
12
  async sync(msg) {
13
    const converted = this.converter.convert(msg);
14
    return this.comparator.compare(converted);
15
  }
16
 
17
  // ein Chat – alle Messages iterieren
18
  async syncChat(chatIdOrObject) {
19
    const messages = await this.provider.collect(chatIdOrObject);
20
    for (const msg of messages) {
21
      await this.sync(msg);
22
    }
23
  }
24
 
25
  // alle Chats – ruft syncChat() pro Chat auf
26
  async syncAll() {
27
    const chats = await this.provider.collectAll();
28
    for (const chat of chats) {
29
      await this.syncChat(chat);
30
    }
31
  }
32
}

Alle Einstiegspunkte landen bei derselben atomaren sync(msg) – der Syncer bleibt dumm, der Provider weiß wie er an die Messages kommt.

Comparator Logik (Chat)

1
Message kommt rein →
2
  ID im Graveyard?                        → ignorieren (Tombstone gewinnt)
3
  ID schon lokal, kein editedAt?          → ignorieren (Duplikat)
4
  ID schon lokal, editedAt neuer?         → lokale Message updaten (Edit gewinnt)
5
  ID neu?                                 → mergen (einfach hinzufügen)
6
  Echter Konflikt?                        → nicht erwartet (UUID v4 + Edit nur eigene
7
                                             Messages macht echte Konflikte praktisch
8
                                             unmöglich) → undefined behavior, reserved for future

onEdit triggert ebenfalls einen Sync – der Comparator vergleicht editedAt und lässt die neuere Version gewinnen.

Default: merge-on-new – kein kompliziertes Conflict-Resolution nötig.

DataChannel-Protokoll

Jede Sync-Message über den DataChannel hat einen gemeinsamen Envelope:

1
{
2
  type:    String,   // siehe unten
3
  payload: Object,   // je nach type
4
  v:       Number,   // Protokoll-Version (aktuell: 1)
5
}

Chat Sync

History – beim Connect, sofort gemergt:

1
// Request
2
{ type: 'sync:request:history', v: 1, payload: { chatId, knownIds: [...] } }
3
 
4
// Response – Peer schickt Messages die nicht in knownIds sind
5
//            und nicht in seinem eigenen Graveyard liegen
6
{ type: 'sync:response:history', v: 1, payload: { chatId, messages: [...] } }

Restorable – beim Connect, für Chat Info Panel:

1
// Request – eigene Graveyard-IDs mitschicken
2
{ type: 'sync:request:restorable', v: 1, payload: { chatId, graveyardIds: [...] } }
3
 
4
// Response – Anzahl + IDs die der Peer hat und lokal im Graveyard liegen
5
{ type: 'sync:response:restorable', v: 1, payload: { chatId, count: 3, ids: [...] } }

Restore – manuell via "Aktualisieren" Button im Chat Info Panel:

1
// Request – gezielt die restorable IDs anfragen
2
{ type: 'sync:request:restore', v: 1, payload: { chatId, ids: [...] } }
3
 
4
// Response – die Messages zu diesen IDs
5
{ type: 'sync:response:restore', v: 1, payload: { chatId, messages: [...] } }

Delete – "Für alle löschen":

1
{ type: 'sync:delete', v: 1, payload: { chatId, id, requestedAt } }

Profile Sync

Beim Connect – Peer fragt aktiv an:

1
{ type: 'sync:request:profile', v: 1, payload: {} }
2
{ type: 'sync:response:profile', v: 1, payload: { ...publicFields, updatedAt } }

Bei Profil-Änderung – Notify-Pattern, Peer zieht selbst:

1
// Sender: "ich hab was neues"
2
{ type: 'sync:notify:profile', v: 1, payload: {} }
3
 
4
// Peer antwortet mit sync:request:profile → normaler Response-Flow

Fehlerfall – Chat Sync

Bleibt eine sync:response:* aus:

1
Timeout: 3s pro Versuch
2
Retries: 3x
3
 
4
Nach 3 Fehlversuchen →
5
  System-Message in Chat einfügen:
6
  { type: 'system', content: 'sync:fail', sentAt: Date.now(), ... }
7
  → beim nächsten Connect automatisch neuer Versuch

System-Messages nutzen dieselbe Message-Struktur (v1) – type: 'system' signalisiert der UI dass kein Nachrichtentext, sondern eine Systemmeldung gerendert werden soll.

Profile Sync und Chat Sync sind vollständig getrennt:

Beide wissen nichts voneinander. Beide können unabhängig getriggert werden.

Welche Profil-Felder gesynct werden bestimmt der User über den public-Block im Profil – nur Felder mit public.{field} === true werden übertragen. Technische Felder (login, clientId, createdAt, preferences) werden niemals gesynct, unabhängig von den Einstellungen.

→ Details: TOOL_chat_concept-profile.md

Chat Info Panel Integration

Wenn der Peer online ist, zeigt das Chat Info Panel:

„3 Nachrichten wiederherstellbar" [Wiederherstellen]

Technisch: beim Connect vergleicht der Comparator die eingehenden IDs mit dem lokalen Graveyard. Die Differenz (IDs die im Graveyard stehen aber vom Peer angeboten werden) ergibt die wiederherstellbare Anzahl.

Wiederherstellung ist immer explizites Opt-in – nie automatisch.

Migration

Migration v0 → v1, migrateV0() und Comparator-Fallback für migrierte Messages sind vollständig dokumentiert in:

→ TOOL_chat_concept-message.md

Offene Punkte