Kanalpunkte: EventSub, Aktionen und Vorlesen mit Freigabe
EventSub ueber WebSocket wurde in ADR-0003 beschlossen und nie gebaut. Jetzt gebaut, weil Kanalpunkt-Einloesungen ueber IRC nur ankommen, wenn die Belohnung eine Texteingabe verlangt - und selbst dann ohne Einloese-ID. Ohne die ID lassen sich Punkte nicht zurueckgeben, wenn eine Aktion scheitert. Zwei Eigenheiten des Protokolls, die im Code stehen: - Ein Abonnement muss innerhalb von 10 Sekunden nach dem Willkommensgruss stehen, sonst schliesst Twitch wieder. - Bei `session_reconnect` wird erst die neue Verbindung aufgebaut und dann die alte geschlossen. Andersherum faellt genau dazwischen eine Einloesung unter den Tisch. Belohnungen werden ueber ihren Titel zugeordnet, wahlweise ueber die stabile ID; liegt beides vor, gewinnt die ID. Eine unbekannte Belohnung ist kein Fehler - es darf welche geben, die das Toolkit nichts angehen. Zum Vorlesen, und warum es eine Warteschlange hat: chat-control.md schliesst TTS fuer Ausbaustufe 1 aus, und der Grund gilt. Kanalpunkte sammeln sich beim Zugucken von allein an und sind damit kaum eine Huerde; ohne Freigabe hat man eine Vorlesefunktion fuer Fremde im eigenen Stream. Vorgabe ist deshalb die Freigabe von Hand, dazu Laengengrenze, Wortfilter, Drossel je Person und Stunde und ein Panikschalter. Zu langer Text wird abgelehnt statt gekuerzt - ein halb vorgelesener Satz ist schlimmer als gar keiner, weil niemand weiss, ob der Rest Absicht war. Gesprochen wird ueber `speechSynthesis`, im Browser eingebaut: kein Cloud-Dienst, keine Kosten, kein Zuschauertext, der das Haus verlaesst. Ob OBS' Browser-Quelle das kann, ist offen - CEF wird teils ohne Sprachausgabe gebaut. Die Seite prueft es beim Start und blendet einen roten Hinweis ein, statt still zu bleiben. Kanalpunkte haben eine eigene Einblendung. Zwischendurch stand hier die des Abos, womit eine eingeloeste Belohnung als "Neues Abo" im Bild gelandet waere - eine Falschmeldung, die in der Aufzeichnung bleibt. Ein Test haelt das fest. `rewards.enabled` ist aus, bis jemand bewusst Belohnungen eintraegt. Eine Aktion, die niemand erwartet, ist im Stream schlimmer als gar keine. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
ZeasyAlexandClaude Opus 5 committed
1 parent
70928235b6
commit
24f0528ff6
4 files changed
+716
No files matched your search
@@ -0,0 +1,98 @@
|
||||
// EventSub liefert Ereignisse, die sich nicht wiederholen lassen. Wer eine
|
||||
// Nachricht falsch deutet, verpasst eine Einloesung - und der Zuschauer hat
|
||||
// die Punkte bezahlt. Deshalb ist das Deuten hier von der Verbindung getrennt
|
||||
// und einzeln geprueft.
|
||||
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { deuten, type EventSubNachricht } from './eventsub.ts';
|
||||
|
||||
const n = (o: unknown): EventSubNachricht => o as EventSubNachricht;
|
||||
|
||||
test('der Willkommensgruss traegt Sitzung und Zeitlimit', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_id: '1', message_type: 'session_welcome' },
|
||||
payload: { session: { id: 'sess-1', keepalive_timeout_seconds: 10, reconnect_url: null } },
|
||||
}));
|
||||
assert.equal(f.art, 'sitzung');
|
||||
assert.equal((f as { sessionId: string }).sessionId, 'sess-1');
|
||||
// 10 s Zeitlimit plus Puffer: der Wachhund soll eine tote Verbindung finden,
|
||||
// nicht eine langsame abwuergen.
|
||||
assert.equal((f as { keepaliveMs: number }).keepaliveMs, 15_000);
|
||||
});
|
||||
|
||||
test('ohne Angabe gilt Twitchs dokumentierte Vorgabe', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'session_welcome' },
|
||||
payload: { session: { id: 's', keepalive_timeout_seconds: null, reconnect_url: null } },
|
||||
}));
|
||||
assert.equal((f as { keepaliveMs: number }).keepaliveMs, 15_000);
|
||||
});
|
||||
|
||||
test('eine Benachrichtigung traegt Typ und Ereignis', () => {
|
||||
const f = deuten(n({
|
||||
metadata: {
|
||||
message_type: 'notification',
|
||||
subscription_type: 'channel.channel_points_custom_reward_redemption.add',
|
||||
},
|
||||
payload: { event: { id: 'red-1', user_name: 'Kevin' } },
|
||||
}));
|
||||
assert.equal(f.art, 'ereignis');
|
||||
assert.match((f as { typ: string }).typ, /reward_redemption\.add$/);
|
||||
assert.equal(((f as { event: Record<string, unknown> }).event)['user_name'], 'Kevin');
|
||||
});
|
||||
|
||||
test('fehlt der Typ in den Kopfdaten, wird er aus dem Abonnement genommen', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'notification' },
|
||||
payload: { subscription: { id: 's', type: 'channel.follow', status: 'enabled' },
|
||||
event: { user_name: 'x' } },
|
||||
}));
|
||||
assert.equal((f as { typ: string }).typ, 'channel.follow');
|
||||
});
|
||||
|
||||
test('eine Benachrichtigung ohne Ereignis wird nicht durchgereicht', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'notification', subscription_type: 'channel.follow' },
|
||||
payload: {},
|
||||
}));
|
||||
assert.equal(f.art, 'unbekannt');
|
||||
});
|
||||
|
||||
test('der Umzug nennt die neue Adresse', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'session_reconnect' },
|
||||
payload: { session: { id: 's', keepalive_timeout_seconds: 10,
|
||||
reconnect_url: 'wss://eventsub.wss.twitch.tv/ws?id=neu' } },
|
||||
}));
|
||||
assert.deepEqual(f, { art: 'umziehen', url: 'wss://eventsub.wss.twitch.tv/ws?id=neu' });
|
||||
});
|
||||
|
||||
test('ein Umzug ohne Adresse wird ignoriert statt zu einer leeren Verbindung zu fuehren', () => {
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'session_reconnect' },
|
||||
payload: { session: { id: 's', keepalive_timeout_seconds: 10, reconnect_url: null } },
|
||||
}));
|
||||
assert.equal(f.art, 'unbekannt');
|
||||
});
|
||||
|
||||
test('ein Entzug wird als solcher erkannt', () => {
|
||||
// Passiert, wenn Abdu die App-Freigabe zurueckzieht. Wiederverbinden hilft
|
||||
// dagegen nichts, deshalb darf es nicht wie ein Netzwerkfehler aussehen.
|
||||
const f = deuten(n({
|
||||
metadata: { message_type: 'revocation' },
|
||||
payload: { subscription: { id: 's', type: 'channel.follow', status: 'authorization_revoked' } },
|
||||
}));
|
||||
assert.deepEqual(f, { art: 'entzogen', typ: 'channel.follow', grund: 'authorization_revoked' });
|
||||
});
|
||||
|
||||
test('ein Lebenszeichen ist ein Lebenszeichen', () => {
|
||||
assert.deepEqual(deuten(n({ metadata: { message_type: 'session_keepalive' }, payload: {} })),
|
||||
{ art: 'lebenszeichen' });
|
||||
});
|
||||
|
||||
test('Unsinn wird verworfen, nicht geraten', () => {
|
||||
for (const muell of [{}, { metadata: {} }, { metadata: { message_type: 'gibtsnicht' }, payload: {} }]) {
|
||||
assert.equal(deuten(n(muell)).art, 'unbekannt');
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,229 @@
|
||||
// EventSub ueber WebSocket. Beschlossen in ADR-0003, gebaut erst jetzt.
|
||||
//
|
||||
// Warum ueberhaupt, wo der Chat doch schon da ist: Kanalpunkt-Einloesungen
|
||||
// kommen ueber IRC nur dann an, wenn die Belohnung eine Texteingabe verlangt -
|
||||
// und selbst dann ohne Einloese-ID. Ohne die ID lassen sich Punkte nicht
|
||||
// zurueckgeben, wenn eine Aktion schiefgeht. Wer Punkte nimmt und nichts
|
||||
// liefert, verliert das Vertrauen schneller als durch jeden Fehler im Bild.
|
||||
//
|
||||
// Ablauf des Protokolls:
|
||||
//
|
||||
// verbinden -> session_welcome (traegt session.id und das Zeitlimit)
|
||||
// -> Abonnements ueber Helix anlegen, mit dieser session.id
|
||||
// -> notification ... notification ... session_keepalive ...
|
||||
//
|
||||
// Zwei Eigenheiten, die man kennen muss:
|
||||
//
|
||||
// * Ein Abonnement muss innerhalb von 10 Sekunden nach dem Willkommensgruss
|
||||
// stehen, sonst schliesst Twitch die Verbindung wieder.
|
||||
// * `session_reconnect` nennt eine neue Adresse. Die alte Verbindung bleibt
|
||||
// offen, bis die neue steht - erst verbinden, dann schliessen, sonst
|
||||
// entsteht genau in dieser Luecke ein verpasstes Ereignis.
|
||||
|
||||
import { logger } from '#core/logger.ts';
|
||||
import { forever } from '#core/retry.ts';
|
||||
|
||||
const log = logger('eventsub');
|
||||
|
||||
export const EVENTSUB_URL = 'wss://eventsub.wss.twitch.tv/ws';
|
||||
|
||||
/**
|
||||
* Wie lange ohne ein Lebenszeichen gewartet wird, bevor neu verbunden wird.
|
||||
* Twitch nennt sein eigenes Zeitlimit im Willkommensgruss (ueblich 10 s); wir
|
||||
* legen Luft drauf, damit ein kurzer Netzhaenger nicht sofort neu verbindet.
|
||||
*/
|
||||
const KEEPALIVE_PUFFER_MS = 5_000;
|
||||
|
||||
export type EventSubNachricht = {
|
||||
metadata: {
|
||||
message_id: string;
|
||||
message_type: 'session_welcome' | 'session_keepalive' | 'notification'
|
||||
| 'session_reconnect' | 'revocation';
|
||||
subscription_type?: string;
|
||||
subscription_version?: string;
|
||||
};
|
||||
payload: {
|
||||
session?: { id: string; keepalive_timeout_seconds: number | null; reconnect_url: string | null };
|
||||
subscription?: { id: string; type: string; status: string };
|
||||
event?: Record<string, unknown>;
|
||||
};
|
||||
};
|
||||
|
||||
/** Ein Abonnement, so wie Helix es entgegennimmt. */
|
||||
export type Abonnement = {
|
||||
type: string;
|
||||
version: string;
|
||||
condition: Record<string, string>;
|
||||
};
|
||||
|
||||
export type EventSubHandlers = {
|
||||
/** Die Sitzung steht. Hier gehoeren die Abonnements angelegt. */
|
||||
onSession: (sessionId: string) => Promise<void>;
|
||||
onNotification: (typ: string, event: Record<string, unknown>) => void;
|
||||
/**
|
||||
* Twitch hat ein Abonnement entzogen - etwa weil das Token zurueckgezogen
|
||||
* wurde. Das ist kein Netzwerkproblem und geht durch Wiederverbinden nicht
|
||||
* weg, deshalb bekommt es einen eigenen Weg.
|
||||
*/
|
||||
onRevocation?: (typ: string, grund: string) => void;
|
||||
onConnected?: () => void;
|
||||
onClosed?: () => void;
|
||||
};
|
||||
|
||||
/**
|
||||
* Was aus einer eingehenden Nachricht folgen soll. Ausgelagert und rein,
|
||||
* damit sich die Faelle pruefen lassen, die im Betrieb selten sind und dann
|
||||
* mitten im Stream zuschlagen.
|
||||
*/
|
||||
export type Folge =
|
||||
| { art: 'sitzung'; sessionId: string; keepaliveMs: number }
|
||||
| { art: 'ereignis'; typ: string; event: Record<string, unknown> }
|
||||
| { art: 'umziehen'; url: string }
|
||||
| { art: 'entzogen'; typ: string; grund: string }
|
||||
| { art: 'lebenszeichen' }
|
||||
| { art: 'unbekannt' };
|
||||
|
||||
export function deuten(n: EventSubNachricht): Folge {
|
||||
switch (n.metadata?.message_type) {
|
||||
case 'session_welcome': {
|
||||
const s = n.payload?.session;
|
||||
if (!s?.id) return { art: 'unbekannt' };
|
||||
// Ohne Angabe 10 Sekunden annehmen, so wie Twitch es dokumentiert.
|
||||
const sek = s.keepalive_timeout_seconds ?? 10;
|
||||
return { art: 'sitzung', sessionId: s.id, keepaliveMs: sek * 1000 + KEEPALIVE_PUFFER_MS };
|
||||
}
|
||||
case 'session_reconnect': {
|
||||
const url = n.payload?.session?.reconnect_url;
|
||||
return url ? { art: 'umziehen', url } : { art: 'unbekannt' };
|
||||
}
|
||||
case 'notification': {
|
||||
const typ = n.metadata.subscription_type ?? n.payload?.subscription?.type ?? '';
|
||||
const event = n.payload?.event;
|
||||
if (!typ || !event) return { art: 'unbekannt' };
|
||||
return { art: 'ereignis', typ, event };
|
||||
}
|
||||
case 'revocation':
|
||||
return {
|
||||
art: 'entzogen',
|
||||
typ: n.payload?.subscription?.type ?? 'unbekannt',
|
||||
grund: n.payload?.subscription?.status ?? 'unbekannt',
|
||||
};
|
||||
case 'session_keepalive':
|
||||
return { art: 'lebenszeichen' };
|
||||
default:
|
||||
return { art: 'unbekannt' };
|
||||
}
|
||||
}
|
||||
|
||||
export type EventSubClient = {
|
||||
run: (signal: AbortSignal) => Promise<void>;
|
||||
isConnected: () => boolean;
|
||||
};
|
||||
|
||||
export function createEventSub(handlers: EventSubHandlers): EventSubClient {
|
||||
let verbunden = false;
|
||||
|
||||
return {
|
||||
run: (signal) => forever(
|
||||
async (sig) => { await einmalVerbinden(EVENTSUB_URL, handlers, sig, (v) => { verbunden = v; }); },
|
||||
{
|
||||
signal,
|
||||
onWait: (ms, n) =>
|
||||
log.warn(`EventSub getrennt, neuer Versuch in ${Math.round(ms / 1000)} s (${n}.)`),
|
||||
},
|
||||
),
|
||||
isConnected: () => verbunden,
|
||||
};
|
||||
}
|
||||
|
||||
function einmalVerbinden(
|
||||
url: string,
|
||||
handlers: EventSubHandlers,
|
||||
signal: AbortSignal,
|
||||
setzeStatus: (v: boolean) => void,
|
||||
): Promise<void> {
|
||||
return new Promise<void>((_erfuellt, ablehnen) => {
|
||||
const ws = new WebSocket(url);
|
||||
let wachhund: ReturnType<typeof setTimeout> | null = null;
|
||||
let umzug: WebSocket | null = null;
|
||||
// Twitch nennt sein Zeitlimit im Willkommensgruss. Bis dahin grosszuegig.
|
||||
let frist = 30_000;
|
||||
|
||||
const abbrechen = (warum: string): void => {
|
||||
if (wachhund) clearTimeout(wachhund);
|
||||
setzeStatus(false);
|
||||
handlers.onClosed?.();
|
||||
try { ws.close(); } catch { /* schon zu */ }
|
||||
try { umzug?.close(); } catch { /* schon zu */ }
|
||||
ablehnen(new Error(warum));
|
||||
};
|
||||
|
||||
signal.addEventListener('abort', () => abbrechen('abgebrochen'), { once: true });
|
||||
|
||||
/** Kommt zu lange nichts, ist die Verbindung tot, ohne es zu melden. */
|
||||
const wachhundStellen = (ms: number): void => {
|
||||
if (wachhund) clearTimeout(wachhund);
|
||||
wachhund = setTimeout(() => abbrechen('kein Lebenszeichen mehr'), ms);
|
||||
};
|
||||
|
||||
ws.addEventListener('open', () => wachhundStellen(30_000));
|
||||
|
||||
ws.addEventListener('message', (ev) => {
|
||||
let nachricht: EventSubNachricht;
|
||||
try { nachricht = JSON.parse(String(ev.data)); } catch { return; }
|
||||
const folge = deuten(nachricht);
|
||||
|
||||
switch (folge.art) {
|
||||
case 'sitzung':
|
||||
frist = folge.keepaliveMs;
|
||||
wachhundStellen(frist);
|
||||
setzeStatus(true);
|
||||
handlers.onConnected?.();
|
||||
// Die Abonnements muessen jetzt angelegt werden. Scheitert das,
|
||||
// haelt Twitch die Verbindung ohnehin nicht lange.
|
||||
void handlers.onSession(folge.sessionId).catch((err: Error) => {
|
||||
log.error(`Abonnements nicht angelegt: ${err.message}`);
|
||||
abbrechen('Abonnements fehlgeschlagen');
|
||||
});
|
||||
break;
|
||||
|
||||
case 'lebenszeichen':
|
||||
wachhundStellen(frist);
|
||||
break;
|
||||
|
||||
case 'ereignis':
|
||||
wachhundStellen(frist);
|
||||
try { handlers.onNotification(folge.typ, folge.event); }
|
||||
catch (err) { log.error(`Ereignis nicht verarbeitet: ${(err as Error).message}`); }
|
||||
break;
|
||||
|
||||
case 'umziehen': {
|
||||
// Erst die neue Verbindung aufbauen, dann die alte schliessen.
|
||||
// Andersherum faellt genau dazwischen ein Ereignis unter den Tisch.
|
||||
log.info('Twitch bittet um Umzug auf eine neue Verbindung');
|
||||
umzug = new WebSocket(folge.url);
|
||||
umzug.addEventListener('open', () => {
|
||||
log.info('Umzug steht, alte Verbindung wird geschlossen');
|
||||
abbrechen('umgezogen');
|
||||
});
|
||||
umzug.addEventListener('error', () => {
|
||||
log.warn('Umzug fehlgeschlagen, bleibe auf der alten Verbindung');
|
||||
umzug = null;
|
||||
});
|
||||
break;
|
||||
}
|
||||
|
||||
case 'entzogen':
|
||||
log.error(`Abonnement entzogen: ${folge.typ} (${folge.grund})`);
|
||||
handlers.onRevocation?.(folge.typ, folge.grund);
|
||||
break;
|
||||
|
||||
default:
|
||||
break;
|
||||
}
|
||||
});
|
||||
|
||||
ws.addEventListener('error', () => abbrechen('WebSocket-Fehler'));
|
||||
ws.addEventListener('close', (ev) => abbrechen(`Verbindung geschlossen (${ev.code})`));
|
||||
});
|
||||
}
|
||||
Reference in new issue
Block a user