@mulingai-npm/redis 3.40.55 → 3.41.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,7 +1,4 @@
|
|
|
1
1
|
import { RedisClient } from '../redis-client';
|
|
2
|
-
import { ListenerPresence } from '../data/listener-presence';
|
|
3
|
-
export { LISTENER_PRESENT_MS, LISTENER_GONE_MS, LISTENER_HEARTBEAT_INTERVAL_MS, listenerPresence } from '../data/listener-presence';
|
|
4
|
-
export type { ListenerPresence } from '../data/listener-presence';
|
|
5
2
|
export type ListenerBreakpoint = 'mobile' | 'desktop' | 'display';
|
|
6
3
|
export type MulingstreamListenerData = {
|
|
7
4
|
listenerId: string;
|
|
@@ -15,54 +12,12 @@ export type MulingstreamListenerData = {
|
|
|
15
12
|
color?: string;
|
|
16
13
|
isListening?: boolean;
|
|
17
14
|
breakpoint?: ListenerBreakpoint;
|
|
18
|
-
/**
|
|
19
|
-
* The listener told us their page went into the background: screen locked,
|
|
20
|
-
* app switched, tab hidden.
|
|
21
|
-
*
|
|
22
|
-
* Set by the client rather than inferred, because the socket cannot tell the
|
|
23
|
-
* difference between a locked phone and a closed tab, and waiting for missed
|
|
24
|
-
* heartbeats to decide costs ninety seconds of translating for somebody who
|
|
25
|
-
* is demonstrably not looking. Cleared by the next heartbeat, which is what a
|
|
26
|
-
* returning page sends immediately.
|
|
27
|
-
*
|
|
28
|
-
* Being away is not being gone. See data/listener-presence.ts.
|
|
29
|
-
*/
|
|
30
|
-
isAway?: boolean;
|
|
31
15
|
};
|
|
32
16
|
export declare class MulingstreamListenerManager {
|
|
33
17
|
private redisClient;
|
|
34
18
|
constructor(redisClient: RedisClient);
|
|
35
19
|
private parseHashData;
|
|
36
20
|
addListener(listenerData: MulingstreamListenerData): Promise<string>;
|
|
37
|
-
/**
|
|
38
|
-
* Every listener currently known, across every room.
|
|
39
|
-
*
|
|
40
|
-
* WHY THIS USES SCAN AND NOT KEYS
|
|
41
|
-
*
|
|
42
|
-
* It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
|
|
43
|
-
* not be. KEYS walks the entire keyspace in one go and Redis is single
|
|
44
|
-
* threaded, so for as long as it runs nothing else in the process is served:
|
|
45
|
-
* not a heartbeat, not a chunk being handed to the pipeline, not a listener
|
|
46
|
-
* joining. The cost is invisible on a development database with a few dozen
|
|
47
|
-
* keys and grows with the busiest moment we will ever have, which is precisely
|
|
48
|
-
* when it must not stall. This is called by the cleanup sweep every sixty
|
|
49
|
-
* seconds, for the entire life of the process, so it would have been the most
|
|
50
|
-
* frequently executed blocking command in the system.
|
|
51
|
-
*
|
|
52
|
-
* SCAN answers the same question in cursored batches, yielding between each,
|
|
53
|
-
* so a large keyspace costs more round trips rather than one long stall. The
|
|
54
|
-
* guarantees are weaker, deliberately: a key added or removed mid-scan may or
|
|
55
|
-
* may not appear. That is exactly right for the caller, which is looking for
|
|
56
|
-
* listeners who went silent minutes ago. One arriving during the scan is one
|
|
57
|
-
* for the next sweep, sixty seconds later, and there is nothing to do about a
|
|
58
|
-
* brand new listener anyway.
|
|
59
|
-
*
|
|
60
|
-
* The pattern also has to reject keys that merely start with `listener:`. The
|
|
61
|
-
* legacy `listener:panel-state:*` keys matched the old pattern and were parsed
|
|
62
|
-
* as listener records, producing entries with NaN timestamps. They never
|
|
63
|
-
* caused harm, since NaN fails every comparison, which is exactly how a
|
|
64
|
-
* defect like that survives.
|
|
65
|
-
*/
|
|
66
21
|
getAllListeners(): Promise<MulingstreamListenerData[]>;
|
|
67
22
|
getListenersByRoom(roomId: string): Promise<MulingstreamListenerData[]>;
|
|
68
23
|
getListener(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
|
|
@@ -75,126 +30,13 @@ export declare class MulingstreamListenerManager {
|
|
|
75
30
|
*/
|
|
76
31
|
updateBreakpoint(listenerIdOrToken: string, breakpoint: ListenerBreakpoint): Promise<MulingstreamListenerData | null>;
|
|
77
32
|
getTargetSocketIdsByRoomLanguage(roomId: string, language: string): Promise<string[]>;
|
|
78
|
-
/**
|
|
79
|
-
* Which languages this room has someone PRESENT on.
|
|
80
|
-
*
|
|
81
|
-
* Feeds consumersFor, which decides what gets translated at all, so an
|
|
82
|
-
* over-generous answer here is money spent on every chunk for nobody. It
|
|
83
|
-
* therefore counts present listeners only: somebody whose phone has been dark
|
|
84
|
-
* for two minutes is receiving nothing, and translating for them is pure loss.
|
|
85
|
-
*
|
|
86
|
-
* It used to count every listener the room had ever registered, including ones
|
|
87
|
-
* whose heartbeat had been silent for fourteen minutes, because the only thing
|
|
88
|
-
* that removed a listener was the cleanup sweep. See data/listener-presence.ts
|
|
89
|
-
* for why that single threshold could not be lowered and had to be split.
|
|
90
|
-
*/
|
|
91
33
|
getUniqueLanguagesByRoom(roomId: string): Promise<string[]>;
|
|
92
|
-
/**
|
|
93
|
-
* How many PRESENT listeners in this room are on a language.
|
|
94
|
-
*
|
|
95
|
-
* Decides whether a guest-added language slot can be handed back, and counts
|
|
96
|
-
* the same population `consumersFor` reads, so the two cannot disagree about
|
|
97
|
-
* whether a language has an audience: a slot is released exactly when the
|
|
98
|
-
* translation for it stops, never one without the other.
|
|
99
|
-
*
|
|
100
|
-
* Present rather than merely registered, and that is the deliberate part. A
|
|
101
|
-
* listener whose phone has been dark for two minutes is not hearing the
|
|
102
|
-
* language, so holding the room's last slot for them denies it to a guest
|
|
103
|
-
* standing in the room who is. If they come back and the slot has gone to
|
|
104
|
-
* somebody else, they choose again from what the room now has; if it is still
|
|
105
|
-
* free they simply take it back.
|
|
106
|
-
*/
|
|
107
|
-
countListenersOnLanguage(roomId: string, language: string): Promise<number>;
|
|
108
|
-
/**
|
|
109
|
-
* The client saying its page went into the background, or came back.
|
|
110
|
-
*
|
|
111
|
-
* This is the difference between reacting to a locked screen at once and
|
|
112
|
-
* reacting to it after three missed heartbeats. Both end in the same state;
|
|
113
|
-
* one of them costs ninety seconds of translation and synthesis for a phone
|
|
114
|
-
* nobody is looking at, on every language in the room.
|
|
115
|
-
*
|
|
116
|
-
* Does NOT touch lastHeartbeat. That field is now also the recorded end of the
|
|
117
|
-
* listener's session, so it has to keep meaning "when they were genuinely last
|
|
118
|
-
* there" and nothing else.
|
|
119
|
-
*/
|
|
120
|
-
setAwayState(listenerIdOrToken: string, isAway: boolean): Promise<MulingstreamListenerData | null>;
|
|
121
|
-
/**
|
|
122
|
-
* Present, away or gone, for one listener. For anything that needs to SHOW the
|
|
123
|
-
* distinction rather than act on it.
|
|
124
|
-
*/
|
|
125
|
-
getPresence(listenerIdOrToken: string): Promise<ListenerPresence | null>;
|
|
126
34
|
updateHeartbeat(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
|
|
127
35
|
getListenerStats(roomId: string): Promise<{
|
|
128
36
|
totalListeners: number;
|
|
129
37
|
languageBreakdown: Record<string, number>;
|
|
130
38
|
}>;
|
|
131
|
-
/**
|
|
132
|
-
* How many people in this room are ACTUALLY RECEIVING translation right now.
|
|
133
|
-
*
|
|
134
|
-
* Church passes turn on this number rather than on how many people joined. A
|
|
135
|
-
* pass is spent only when translation reached a human being, so somebody
|
|
136
|
-
* sitting on the join screen must not burn a church's pass.
|
|
137
|
-
*
|
|
138
|
-
* ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
|
|
139
|
-
*
|
|
140
|
-
* Corrected 2026-08-19. This used to require `isListening`, the audio
|
|
141
|
-
* playback flag, so a guest who joined, chose their language and sat reading
|
|
142
|
-
* the translated text counted for nothing: the pass clock stayed at zero
|
|
143
|
-
* until they pressed Listening. David found it on a phone, and the counting
|
|
144
|
-
* spec had said otherwise all along, in as many words: "the listener session
|
|
145
|
-
* is open AND we are delivering translated output to it, audio or text".
|
|
146
|
-
*
|
|
147
|
-
* The reading is the product. A deaf guest, a guest in a quiet room, a guest
|
|
148
|
-
* with no headphones and a guest who simply prefers to read are all being
|
|
149
|
-
* served, all costing us translation on every chunk, and none of them are
|
|
150
|
-
* pressing an audio button. Charging only for audio would have meant a
|
|
151
|
-
* church whose congregation reads never spends a pass, which sounds generous
|
|
152
|
-
* until you notice we are paying for every word of it.
|
|
153
|
-
*
|
|
154
|
-
* So the test is PRESENCE, and nothing else. Presence already means joined,
|
|
155
|
-
* in a language, and with a heartbeat inside the last ninety seconds, which
|
|
156
|
-
* is exactly the population `consumersFor` is translating for. Whether they
|
|
157
|
-
* also chose to hear it is not our business, and the spec is explicit that we
|
|
158
|
-
* do not police attention: a phone in a pocket with audio playing is
|
|
159
|
-
* listening, and a phone in a hand with text on it is reading.
|
|
160
|
-
*
|
|
161
|
-
* `isListening` keeps its real job, which is a different question: whether to
|
|
162
|
-
* SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
|
|
163
|
-
* expensive thing we produce and nobody should pay to generate audio no one
|
|
164
|
-
* is playing. Text is already produced for the room either way.
|
|
165
|
-
*/
|
|
166
|
-
getReceivingCount(roomId: string): Promise<number>;
|
|
167
39
|
private capKey;
|
|
168
|
-
private previewKey;
|
|
169
|
-
private previewCountKey;
|
|
170
|
-
/** Open a preview window on one language. Re-pressing simply extends it. */
|
|
171
|
-
openPreview(roomId: string, language: string, windowSeconds: number): Promise<void>;
|
|
172
|
-
/** Seconds left on a language's preview window, or 0 when none is open. */
|
|
173
|
-
getPreviewRemaining(roomId: string, language: string): Promise<number>;
|
|
174
|
-
/**
|
|
175
|
-
* Which of `candidates` currently have a preview open.
|
|
176
|
-
*
|
|
177
|
-
* Takes the candidate list rather than scanning for a pattern on purpose:
|
|
178
|
-
* KEYS and SCAN against a live Redis to answer a question asked on every
|
|
179
|
-
* audio chunk is the kind of thing that is fine until it is not.
|
|
180
|
-
*/
|
|
181
|
-
getPreviewLanguages(roomId: string, candidates: string[]): Promise<string[]>;
|
|
182
|
-
/**
|
|
183
|
-
* Count one press against the room's allowance and say whether it is allowed.
|
|
184
|
-
*
|
|
185
|
-
* The cap exists because a preview translates for real. Without it, holding
|
|
186
|
-
* the button open is a way to run a translation service for nothing, and the
|
|
187
|
-
* obvious abuse is someone using a speaker preview as a free manual
|
|
188
|
-
* translation tool. The counter's own TTL resets the allowance, so a church
|
|
189
|
-
* running a genuine service every week is never permanently locked out.
|
|
190
|
-
*/
|
|
191
|
-
consumePreviewAllowance(roomId: string, maxPresses: number, resetSeconds: number): Promise<{
|
|
192
|
-
allowed: boolean;
|
|
193
|
-
used: number;
|
|
194
|
-
remaining: number;
|
|
195
|
-
}>;
|
|
196
|
-
/** Presses already spent in the current window. Read only, never increments. */
|
|
197
|
-
getPreviewUsage(roomId: string): Promise<number>;
|
|
198
40
|
/**
|
|
199
41
|
* Cache the room's listener cap. Called by the speaker service at go-live and
|
|
200
42
|
* on reconnect; `ttlSeconds` should comfortably exceed a session so the key
|
|
@@ -1,12 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.MulingstreamListenerManager =
|
|
4
|
-
const listener_presence_1 = require("../data/listener-presence");
|
|
5
|
-
var listener_presence_2 = require("../data/listener-presence");
|
|
6
|
-
Object.defineProperty(exports, "LISTENER_PRESENT_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_PRESENT_MS; } });
|
|
7
|
-
Object.defineProperty(exports, "LISTENER_GONE_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_GONE_MS; } });
|
|
8
|
-
Object.defineProperty(exports, "LISTENER_HEARTBEAT_INTERVAL_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_HEARTBEAT_INTERVAL_MS; } });
|
|
9
|
-
Object.defineProperty(exports, "listenerPresence", { enumerable: true, get: function () { return listener_presence_2.listenerPresence; } });
|
|
3
|
+
exports.MulingstreamListenerManager = void 0;
|
|
10
4
|
const EXPIRATION = 24 * 60 * 60; // 24 hours in seconds
|
|
11
5
|
/**
|
|
12
6
|
* Generates a bright RGB color suitable for dark backgrounds.
|
|
@@ -54,8 +48,7 @@ class MulingstreamListenerManager {
|
|
|
54
48
|
language: data.language || '',
|
|
55
49
|
color: data.color || '',
|
|
56
50
|
isListening: data.isListening === 'true',
|
|
57
|
-
breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined
|
|
58
|
-
isAway: data.isAway === 'true'
|
|
51
|
+
breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined
|
|
59
52
|
};
|
|
60
53
|
}
|
|
61
54
|
// Creates a new listener.
|
|
@@ -81,60 +74,25 @@ class MulingstreamListenerManager {
|
|
|
81
74
|
language: (_c = listenerData.language) !== null && _c !== void 0 ? _c : '',
|
|
82
75
|
color,
|
|
83
76
|
isListening: 'false',
|
|
84
|
-
breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : ''
|
|
85
|
-
// A listener who just joined is looking at the page by definition.
|
|
86
|
-
isAway: 'false'
|
|
77
|
+
breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : ''
|
|
87
78
|
});
|
|
88
79
|
// expire listener
|
|
89
80
|
await this.redisClient.expire(`listener:${listenerId}`, EXPIRATION);
|
|
90
81
|
return listenerId;
|
|
91
82
|
}
|
|
92
|
-
/**
|
|
93
|
-
* Every listener currently known, across every room.
|
|
94
|
-
*
|
|
95
|
-
* WHY THIS USES SCAN AND NOT KEYS
|
|
96
|
-
*
|
|
97
|
-
* It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
|
|
98
|
-
* not be. KEYS walks the entire keyspace in one go and Redis is single
|
|
99
|
-
* threaded, so for as long as it runs nothing else in the process is served:
|
|
100
|
-
* not a heartbeat, not a chunk being handed to the pipeline, not a listener
|
|
101
|
-
* joining. The cost is invisible on a development database with a few dozen
|
|
102
|
-
* keys and grows with the busiest moment we will ever have, which is precisely
|
|
103
|
-
* when it must not stall. This is called by the cleanup sweep every sixty
|
|
104
|
-
* seconds, for the entire life of the process, so it would have been the most
|
|
105
|
-
* frequently executed blocking command in the system.
|
|
106
|
-
*
|
|
107
|
-
* SCAN answers the same question in cursored batches, yielding between each,
|
|
108
|
-
* so a large keyspace costs more round trips rather than one long stall. The
|
|
109
|
-
* guarantees are weaker, deliberately: a key added or removed mid-scan may or
|
|
110
|
-
* may not appear. That is exactly right for the caller, which is looking for
|
|
111
|
-
* listeners who went silent minutes ago. One arriving during the scan is one
|
|
112
|
-
* for the next sweep, sixty seconds later, and there is nothing to do about a
|
|
113
|
-
* brand new listener anyway.
|
|
114
|
-
*
|
|
115
|
-
* The pattern also has to reject keys that merely start with `listener:`. The
|
|
116
|
-
* legacy `listener:panel-state:*` keys matched the old pattern and were parsed
|
|
117
|
-
* as listener records, producing entries with NaN timestamps. They never
|
|
118
|
-
* caused harm, since NaN fails every comparison, which is exactly how a
|
|
119
|
-
* defect like that survives.
|
|
120
|
-
*/
|
|
121
83
|
async getAllListeners() {
|
|
84
|
+
// get all keys that match 'listener:*'
|
|
85
|
+
// TODO: if we have many keys, consider using SCAN instead of KEYS to avoid performance issues.
|
|
86
|
+
const keys = await this.redisClient.keys('listener:*');
|
|
87
|
+
if (!keys || keys.length === 0) {
|
|
88
|
+
return [];
|
|
89
|
+
}
|
|
90
|
+
// fetch each hash with HGETALL
|
|
122
91
|
const listeners = [];
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
for (const key of keys || []) {
|
|
128
|
-
// `listener:{id}` only. Anything with a further colon belongs to
|
|
129
|
-
// some other feature that happens to share the prefix.
|
|
130
|
-
if (key.split(':').length !== 2)
|
|
131
|
-
continue;
|
|
132
|
-
const data = await this.redisClient.hgetall(key);
|
|
133
|
-
if (!data || Object.keys(data).length === 0)
|
|
134
|
-
continue;
|
|
135
|
-
listeners.push(this.parseHashData(data));
|
|
136
|
-
}
|
|
137
|
-
} while (cursor !== 0);
|
|
92
|
+
for (const key of keys) {
|
|
93
|
+
const data = await this.redisClient.hgetall(key);
|
|
94
|
+
listeners.push(this.parseHashData(data));
|
|
95
|
+
}
|
|
138
96
|
return listeners;
|
|
139
97
|
}
|
|
140
98
|
async getListenersByRoom(roomId) {
|
|
@@ -231,23 +189,13 @@ class MulingstreamListenerManager {
|
|
|
231
189
|
});
|
|
232
190
|
return filteredListeners.map((listener) => listener.socketId);
|
|
233
191
|
}
|
|
234
|
-
/**
|
|
235
|
-
* Which languages this room has someone PRESENT on.
|
|
236
|
-
*
|
|
237
|
-
* Feeds consumersFor, which decides what gets translated at all, so an
|
|
238
|
-
* over-generous answer here is money spent on every chunk for nobody. It
|
|
239
|
-
* therefore counts present listeners only: somebody whose phone has been dark
|
|
240
|
-
* for two minutes is receiving nothing, and translating for them is pure loss.
|
|
241
|
-
*
|
|
242
|
-
* It used to count every listener the room had ever registered, including ones
|
|
243
|
-
* whose heartbeat had been silent for fourteen minutes, because the only thing
|
|
244
|
-
* that removed a listener was the cleanup sweep. See data/listener-presence.ts
|
|
245
|
-
* for why that single threshold could not be lowered and had to be split.
|
|
246
|
-
*/
|
|
247
192
|
async getUniqueLanguagesByRoom(roomId) {
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
193
|
+
// 1) Fetch all listeners for the room.
|
|
194
|
+
// (This includes inactive ones, but feel free to filter out isActive === false if you only want active ones.)
|
|
195
|
+
const listeners = await this.getListenersByRoom(roomId);
|
|
196
|
+
// if I wanted to get only active listeners
|
|
197
|
+
// const listeners = (await this.getListenersByRoom(roomId)).filter(l => l.isActive);
|
|
198
|
+
// 2) Count how many times each language appears.
|
|
251
199
|
const languageCountMap = {};
|
|
252
200
|
for (const listener of listeners) {
|
|
253
201
|
// skip blank/unset language
|
|
@@ -263,57 +211,6 @@ class MulingstreamListenerManager {
|
|
|
263
211
|
// 4) Map back to just the language strings in order
|
|
264
212
|
return sortedEntries.map(([language]) => language);
|
|
265
213
|
}
|
|
266
|
-
/**
|
|
267
|
-
* How many PRESENT listeners in this room are on a language.
|
|
268
|
-
*
|
|
269
|
-
* Decides whether a guest-added language slot can be handed back, and counts
|
|
270
|
-
* the same population `consumersFor` reads, so the two cannot disagree about
|
|
271
|
-
* whether a language has an audience: a slot is released exactly when the
|
|
272
|
-
* translation for it stops, never one without the other.
|
|
273
|
-
*
|
|
274
|
-
* Present rather than merely registered, and that is the deliberate part. A
|
|
275
|
-
* listener whose phone has been dark for two minutes is not hearing the
|
|
276
|
-
* language, so holding the room's last slot for them denies it to a guest
|
|
277
|
-
* standing in the room who is. If they come back and the slot has gone to
|
|
278
|
-
* somebody else, they choose again from what the room now has; if it is still
|
|
279
|
-
* free they simply take it back.
|
|
280
|
-
*/
|
|
281
|
-
async countListenersOnLanguage(roomId, language) {
|
|
282
|
-
if (!roomId || !language)
|
|
283
|
-
return 0;
|
|
284
|
-
const now = Date.now();
|
|
285
|
-
const listeners = await this.getListenersByRoom(roomId);
|
|
286
|
-
return listeners.filter((listener) => listener.language === language && (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now)).length;
|
|
287
|
-
}
|
|
288
|
-
/**
|
|
289
|
-
* The client saying its page went into the background, or came back.
|
|
290
|
-
*
|
|
291
|
-
* This is the difference between reacting to a locked screen at once and
|
|
292
|
-
* reacting to it after three missed heartbeats. Both end in the same state;
|
|
293
|
-
* one of them costs ninety seconds of translation and synthesis for a phone
|
|
294
|
-
* nobody is looking at, on every language in the room.
|
|
295
|
-
*
|
|
296
|
-
* Does NOT touch lastHeartbeat. That field is now also the recorded end of the
|
|
297
|
-
* listener's session, so it has to keep meaning "when they were genuinely last
|
|
298
|
-
* there" and nothing else.
|
|
299
|
-
*/
|
|
300
|
-
async setAwayState(listenerIdOrToken, isAway) {
|
|
301
|
-
const listener = await this.getListener(listenerIdOrToken);
|
|
302
|
-
if (!listener)
|
|
303
|
-
return null;
|
|
304
|
-
await this.redisClient.hset(`listener:${listener.listenerId}`, { isAway: isAway.toString() });
|
|
305
|
-
return { ...listener, isAway };
|
|
306
|
-
}
|
|
307
|
-
/**
|
|
308
|
-
* Present, away or gone, for one listener. For anything that needs to SHOW the
|
|
309
|
-
* distinction rather than act on it.
|
|
310
|
-
*/
|
|
311
|
-
async getPresence(listenerIdOrToken) {
|
|
312
|
-
const listener = await this.getListener(listenerIdOrToken);
|
|
313
|
-
if (!listener)
|
|
314
|
-
return null;
|
|
315
|
-
return (0, listener_presence_1.listenerPresence)(listener.lastHeartbeat, listener.isAway === true);
|
|
316
|
-
}
|
|
317
214
|
async updateHeartbeat(listenerIdOrToken) {
|
|
318
215
|
const listener = await this.getListener(listenerIdOrToken);
|
|
319
216
|
if (!listener) {
|
|
@@ -321,16 +218,9 @@ class MulingstreamListenerManager {
|
|
|
321
218
|
return null;
|
|
322
219
|
}
|
|
323
220
|
const now = Date.now();
|
|
324
|
-
// Update the heartbeat timestamp
|
|
325
|
-
//
|
|
326
|
-
// A heartbeat only arrives from a page that is running, so receiving one is
|
|
327
|
-
// proof the listener is back: an explicit "I have returned" event would be
|
|
328
|
-
// a second way of saying the same thing, and a second way to get it wrong.
|
|
329
|
-
// A returning page sends a heartbeat immediately on visibility, so this is
|
|
330
|
-
// as fast as anything else could be.
|
|
221
|
+
// Update the heartbeat timestamp
|
|
331
222
|
await this.redisClient.hset(`listener:${listener.listenerId}`, {
|
|
332
|
-
lastHeartbeat: now.toString()
|
|
333
|
-
isAway: 'false'
|
|
223
|
+
lastHeartbeat: now.toString()
|
|
334
224
|
});
|
|
335
225
|
// Reset expiration on activity
|
|
336
226
|
await this.redisClient.expire(`listener:${listener.listenerId}`, EXPIRATION);
|
|
@@ -349,46 +239,6 @@ class MulingstreamListenerManager {
|
|
|
349
239
|
languageBreakdown
|
|
350
240
|
};
|
|
351
241
|
}
|
|
352
|
-
/**
|
|
353
|
-
* How many people in this room are ACTUALLY RECEIVING translation right now.
|
|
354
|
-
*
|
|
355
|
-
* Church passes turn on this number rather than on how many people joined. A
|
|
356
|
-
* pass is spent only when translation reached a human being, so somebody
|
|
357
|
-
* sitting on the join screen must not burn a church's pass.
|
|
358
|
-
*
|
|
359
|
-
* ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
|
|
360
|
-
*
|
|
361
|
-
* Corrected 2026-08-19. This used to require `isListening`, the audio
|
|
362
|
-
* playback flag, so a guest who joined, chose their language and sat reading
|
|
363
|
-
* the translated text counted for nothing: the pass clock stayed at zero
|
|
364
|
-
* until they pressed Listening. David found it on a phone, and the counting
|
|
365
|
-
* spec had said otherwise all along, in as many words: "the listener session
|
|
366
|
-
* is open AND we are delivering translated output to it, audio or text".
|
|
367
|
-
*
|
|
368
|
-
* The reading is the product. A deaf guest, a guest in a quiet room, a guest
|
|
369
|
-
* with no headphones and a guest who simply prefers to read are all being
|
|
370
|
-
* served, all costing us translation on every chunk, and none of them are
|
|
371
|
-
* pressing an audio button. Charging only for audio would have meant a
|
|
372
|
-
* church whose congregation reads never spends a pass, which sounds generous
|
|
373
|
-
* until you notice we are paying for every word of it.
|
|
374
|
-
*
|
|
375
|
-
* So the test is PRESENCE, and nothing else. Presence already means joined,
|
|
376
|
-
* in a language, and with a heartbeat inside the last ninety seconds, which
|
|
377
|
-
* is exactly the population `consumersFor` is translating for. Whether they
|
|
378
|
-
* also chose to hear it is not our business, and the spec is explicit that we
|
|
379
|
-
* do not police attention: a phone in a pocket with audio playing is
|
|
380
|
-
* listening, and a phone in a hand with text on it is reading.
|
|
381
|
-
*
|
|
382
|
-
* `isListening` keeps its real job, which is a different question: whether to
|
|
383
|
-
* SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
|
|
384
|
-
* expensive thing we produce and nobody should pay to generate audio no one
|
|
385
|
-
* is playing. Text is already produced for the room either way.
|
|
386
|
-
*/
|
|
387
|
-
async getReceivingCount(roomId) {
|
|
388
|
-
const now = Date.now();
|
|
389
|
-
const listeners = await this.getListenersByRoom(roomId);
|
|
390
|
-
return listeners.filter((l) => (0, listener_presence_1.isListenerPresent)(l.lastHeartbeat, l.isAway === true, now)).length;
|
|
391
|
-
}
|
|
392
242
|
// ─── Per-room listener capacity (design B, 2026-07-09) ────────────────────
|
|
393
243
|
// The cap value is the room owner's plan `max_audience`, resolved ONCE by the
|
|
394
244
|
// speaker service when it goes live (it already fetches the plan entitlements)
|
|
@@ -400,82 +250,6 @@ class MulingstreamListenerManager {
|
|
|
400
250
|
capKey(roomId) {
|
|
401
251
|
return `room:${roomId}:listener-cap`;
|
|
402
252
|
}
|
|
403
|
-
/*
|
|
404
|
-
* SPEAKER PREVIEW
|
|
405
|
-
*
|
|
406
|
-
* A speaker looking at their own translation feed is a consumer of
|
|
407
|
-
* translation but must never be a payer for it: nobody should be able to
|
|
408
|
-
* spend a church's pass, or their own credits, by watching their own screen.
|
|
409
|
-
* So a preview is a short window they open deliberately, not a state they
|
|
410
|
-
* fall into by leaving a tab open.
|
|
411
|
-
*
|
|
412
|
-
* In Redis rather than in the pipeline's memory because the request arrives
|
|
413
|
-
* at the room service and the decision is read by the pipeline service, and
|
|
414
|
-
* because a pipeline replica restarting mid window must not silently start
|
|
415
|
-
* translating for nobody. The TTL IS the expiry: nothing has to remember to
|
|
416
|
-
* close it, and a crash fails in the safe direction.
|
|
417
|
-
*/
|
|
418
|
-
previewKey(roomId, language) {
|
|
419
|
-
return `room:${roomId}:preview:${language}`;
|
|
420
|
-
}
|
|
421
|
-
previewCountKey(roomId) {
|
|
422
|
-
return `room:${roomId}:preview-count`;
|
|
423
|
-
}
|
|
424
|
-
/** Open a preview window on one language. Re-pressing simply extends it. */
|
|
425
|
-
async openPreview(roomId, language, windowSeconds) {
|
|
426
|
-
if (!roomId || !language || windowSeconds <= 0)
|
|
427
|
-
return;
|
|
428
|
-
const key = this.previewKey(roomId, language);
|
|
429
|
-
await this.redisClient.set(key, '1');
|
|
430
|
-
await this.redisClient.expire(key, Math.floor(windowSeconds));
|
|
431
|
-
}
|
|
432
|
-
/** Seconds left on a language's preview window, or 0 when none is open. */
|
|
433
|
-
async getPreviewRemaining(roomId, language) {
|
|
434
|
-
const ttl = await this.redisClient.ttl(this.previewKey(roomId, language));
|
|
435
|
-
return ttl > 0 ? ttl : 0;
|
|
436
|
-
}
|
|
437
|
-
/**
|
|
438
|
-
* Which of `candidates` currently have a preview open.
|
|
439
|
-
*
|
|
440
|
-
* Takes the candidate list rather than scanning for a pattern on purpose:
|
|
441
|
-
* KEYS and SCAN against a live Redis to answer a question asked on every
|
|
442
|
-
* audio chunk is the kind of thing that is fine until it is not.
|
|
443
|
-
*/
|
|
444
|
-
async getPreviewLanguages(roomId, candidates) {
|
|
445
|
-
if (!roomId || candidates.length === 0)
|
|
446
|
-
return [];
|
|
447
|
-
const open = [];
|
|
448
|
-
for (const language of candidates) {
|
|
449
|
-
if (await this.redisClient.get(this.previewKey(roomId, language)))
|
|
450
|
-
open.push(language);
|
|
451
|
-
}
|
|
452
|
-
return open;
|
|
453
|
-
}
|
|
454
|
-
/**
|
|
455
|
-
* Count one press against the room's allowance and say whether it is allowed.
|
|
456
|
-
*
|
|
457
|
-
* The cap exists because a preview translates for real. Without it, holding
|
|
458
|
-
* the button open is a way to run a translation service for nothing, and the
|
|
459
|
-
* obvious abuse is someone using a speaker preview as a free manual
|
|
460
|
-
* translation tool. The counter's own TTL resets the allowance, so a church
|
|
461
|
-
* running a genuine service every week is never permanently locked out.
|
|
462
|
-
*/
|
|
463
|
-
async consumePreviewAllowance(roomId, maxPresses, resetSeconds) {
|
|
464
|
-
const key = this.previewCountKey(roomId);
|
|
465
|
-
const used = await this.redisClient.incr(key);
|
|
466
|
-
// Only the first press starts the clock, so the window is a fixed period
|
|
467
|
-
// from first use rather than one that slides forward on every press.
|
|
468
|
-
if (used === 1)
|
|
469
|
-
await this.redisClient.expire(key, Math.floor(resetSeconds));
|
|
470
|
-
const allowed = used <= maxPresses;
|
|
471
|
-
return { allowed, used, remaining: Math.max(0, maxPresses - used) };
|
|
472
|
-
}
|
|
473
|
-
/** Presses already spent in the current window. Read only, never increments. */
|
|
474
|
-
async getPreviewUsage(roomId) {
|
|
475
|
-
const raw = await this.redisClient.get(this.previewCountKey(roomId));
|
|
476
|
-
const used = raw ? parseInt(raw, 10) : 0;
|
|
477
|
-
return Number.isFinite(used) && used > 0 ? used : 0;
|
|
478
|
-
}
|
|
479
253
|
/**
|
|
480
254
|
* Cache the room's listener cap. Called by the speaker service at go-live and
|
|
481
255
|
* on reconnect; `ttlSeconds` should comfortably exceed a session so the key
|
|
@@ -556,7 +330,6 @@ class MulingstreamListenerManager {
|
|
|
556
330
|
* Used by pipeline to determine which languages need TTS generation.
|
|
557
331
|
*/
|
|
558
332
|
async getLanguagesWithActiveListeners(roomId) {
|
|
559
|
-
const now = Date.now();
|
|
560
333
|
const listeners = await this.getListenersByRoom(roomId);
|
|
561
334
|
const languageCountMap = {};
|
|
562
335
|
for (const listener of listeners) {
|
|
@@ -564,10 +337,6 @@ class MulingstreamListenerManager {
|
|
|
564
337
|
continue;
|
|
565
338
|
if (!listener.isListening)
|
|
566
339
|
continue;
|
|
567
|
-
// Speech synthesis is the most expensive thing we do. A language whose
|
|
568
|
-
// only listener has a dark phone must not be synthesised.
|
|
569
|
-
if (!(0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now))
|
|
570
|
-
continue;
|
|
571
340
|
const lang = listener.language;
|
|
572
341
|
languageCountMap[lang] = (languageCountMap[lang] || 0) + 1;
|
|
573
342
|
}
|
package/package.json
CHANGED
|
@@ -1,34 +1,34 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@mulingai-npm/redis",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"main": "dist/index.js",
|
|
5
|
-
"types": "dist/index.d.ts",
|
|
6
|
-
"repository": {
|
|
7
|
-
"type": "git",
|
|
8
|
-
"url": "https://github.com/mulingai/mulingai-backend.git"
|
|
9
|
-
},
|
|
10
|
-
"publishConfig": {
|
|
11
|
-
"registry": "https://registry.npmjs.org/"
|
|
12
|
-
},
|
|
13
|
-
"private": false,
|
|
14
|
-
"scripts": {
|
|
15
|
-
"dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
|
|
16
|
-
"build": "rm -f tsconfig.tsbuildinfo && tsc",
|
|
17
|
-
"prepublishOnly": "npm run build"
|
|
18
|
-
},
|
|
19
|
-
"dependencies": {
|
|
20
|
-
"ioredis": "^5.6.0",
|
|
21
|
-
"uuid": "^11.1.0"
|
|
22
|
-
},
|
|
23
|
-
"devDependencies": {
|
|
24
|
-
"concurrently": "^9.1.2",
|
|
25
|
-
"copyfiles": "^2.4.1",
|
|
26
|
-
"nodemon": "^3.1.9",
|
|
27
|
-
"typescript": "^4.9.5"
|
|
28
|
-
},
|
|
29
|
-
"files": [
|
|
30
|
-
"dist",
|
|
31
|
-
"package.json",
|
|
32
|
-
"README.md"
|
|
33
|
-
]
|
|
34
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@mulingai-npm/redis",
|
|
3
|
+
"version": "3.41.0",
|
|
4
|
+
"main": "dist/index.js",
|
|
5
|
+
"types": "dist/index.d.ts",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "https://github.com/mulingai/mulingai-backend.git"
|
|
9
|
+
},
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"registry": "https://registry.npmjs.org/"
|
|
12
|
+
},
|
|
13
|
+
"private": false,
|
|
14
|
+
"scripts": {
|
|
15
|
+
"dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
|
|
16
|
+
"build": "rm -f tsconfig.tsbuildinfo && tsc",
|
|
17
|
+
"prepublishOnly": "npm run build"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"ioredis": "^5.6.0",
|
|
21
|
+
"uuid": "^11.1.0"
|
|
22
|
+
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"concurrently": "^9.1.2",
|
|
25
|
+
"copyfiles": "^2.4.1",
|
|
26
|
+
"nodemon": "^3.1.9",
|
|
27
|
+
"typescript": "^4.9.5"
|
|
28
|
+
},
|
|
29
|
+
"files": [
|
|
30
|
+
"dist",
|
|
31
|
+
"package.json",
|
|
32
|
+
"README.md"
|
|
33
|
+
]
|
|
34
|
+
}
|