Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

fix(dictation): Fail over a stalled managed Orukeet stream within seconds (#2387)

Chad Pihadef8b7c40368
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 1c4d902b7..0a45735ee 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -1,4 +1,4 @@
-const { OrukeetStreaming } = require("./orukeetStreaming");
+const { OrukeetStreaming, MANAGED_STREAM_OPTIONS } = require("./orukeetStreaming");
const { connectManagedOrukeet } = require("./orukeetCloudSession");
const { ipcMain, app, shell, BrowserWindow, systemPreferences, net, session } = require("electron");
const path = require("path");
@@ -8436,11 +8436,9 @@ class IPCHandlers {
// default lives here, at the boundary, so the token allowlist stays
// fail-closed for genuinely unknown providers (#1624).
const provider = options.provider ?? "openai-realtime";
- // Managed Cloud retains the capture for batch fallback. A refused
- // commit must close this attempt instead of retrying for 30 seconds.
const streaming =
provider === "orukeet"
- ? new OrukeetStreaming({ retryCapacity: !isCloud })
+ ? new OrukeetStreaming(isCloud ? MANAGED_STREAM_OPTIONS : {})
: new OpenAIRealtimeStreaming();
setupDictationCallbacks(streaming, event);
// Assign before the token fetch (a real network round trip) so
diff --git a/src/helpers/orukeetStreaming.js b/src/helpers/orukeetStreaming.js
index 259fad87b..2f726970f 100644
--- a/src/helpers/orukeetStreaming.js
+++ b/src/helpers/orukeetStreaming.js
@@ -1,6 +1,22 @@
const WebSocket = require("ws");
const MAX_PENDING_BYTES = 2 * 1024 * 1024;
+// Mono 16 kHz PCM16.
+const BYTES_PER_SECOND = 32000;
+const MAX_FINAL_WAIT_MS = 30000;
+
+// Managed Cloud keeps the capture for a batch upload, so a stalled or
+// unreachable GPU host should fail over within seconds rather than hold the
+// user for the full 30 s budget. BYOK servers keep the defaults: they have no
+// fallback, and a busy self-hosted CPU may legitimately answer slowly.
+const MANAGED_STREAM_OPTIONS = {
+ // A refused commit must close this attempt instead of retrying for 30 s.
+ retryCapacity: false,
+ timeoutMs: 10000,
+ // Long enough to ride out a Wi-Fi roam or cellular hand-off.
+ livenessMs: 8000,
+ finalTimeoutMs: (audioSeconds) => 5000 + audioSeconds * 100,
+};
function languageMetadata(message) {
const language = message.language;
@@ -59,10 +75,14 @@ class OrukeetStreaming {
createSocket = (url, options, protocols) => new WebSocket(url, protocols, options),
timeoutMs = 30000,
retryCapacity = true,
+ livenessMs = null,
+ finalTimeoutMs = () => timeoutMs,
} = {}) {
this.createSocket = createSocket;
this.timeoutMs = timeoutMs;
this.retryCapacity = retryCapacity;
+ this.livenessMs = livenessMs;
+ this.finalTimeoutMs = finalTimeoutMs;
this.ws = null;
this.isConnected = false;
this.pendingAudio = [];
@@ -143,7 +163,7 @@ class OrukeetStreaming {
) {
throw new Error("Orukeet server does not support mono 16 kHz PCM");
}
- this.maxAudioBytes = message.max_seconds * 32000;
+ this.maxAudioBytes = message.max_seconds * BYTES_PER_SECOND;
this.isConnected = true;
this.connecting = false;
for (const data of this.pendingAudio) this.writeAudio(data);
@@ -155,6 +175,7 @@ class OrukeetStreaming {
if (this.isConnected) this.sendControl({ type: "ping" });
}, 15000);
this.keepAlive.unref?.();
+ this.startLivenessCheck();
} else if (message.type === "language") {
// Advisory audio-language metadata never commits a transcript or triggers a paste.
// The final message remains authoritative for this recording.
@@ -191,6 +212,44 @@ class OrukeetStreaming {
}
}
+ // A wedged server can keep its TCP connection open, so a stall only shows up
+ // as missing pongs. The check arms on the first pong: a server that never
+ // answers pings keeps today's behaviour instead of failing every recording.
+ // A pending commit is bounded by the final deadline instead, since inference
+ // may hold the server's event loop.
+ startLivenessCheck() {
+ if (!this.livenessMs) return;
+ const intervalMs = this.livenessMs / 2;
+ let lastHeardAt = null;
+ let lastCheckAt = performance.now();
+ this.ws.on("pong", () => {
+ lastHeardAt = performance.now();
+ });
+ this.ws.on("message", () => {
+ if (lastHeardAt !== null) lastHeardAt = performance.now();
+ });
+ const check = () => {
+ if (this.intentionalClose || this.failure || this.finalPromise) return;
+ const now = performance.now();
+ const late = now - lastCheckAt >= intervalMs * 1.5;
+ lastCheckAt = now;
+ if (lastHeardAt !== null) {
+ // A late tick means this process was held up (a blocked main thread or
+ // App Nap), not the server, so the next ping gets a full window.
+ if (late) lastHeardAt = now;
+ else if (now - lastHeardAt > this.livenessMs) {
+ return this.fail(new Error("Orukeet server stopped responding"));
+ }
+ }
+ this.ws.ping();
+ };
+ check();
+ // After a blocked main thread, timers run before pending socket reads;
+ // setImmediate lets a pong that already arrived count first.
+ this.livenessTimer = setInterval(() => setImmediate(check), intervalMs);
+ this.livenessTimer.unref?.();
+ }
+
sendAudio(data) {
if (this.intentionalClose || this.failure || this.finalPromise) return;
const buffer = Buffer.from(data);
@@ -219,12 +278,12 @@ class OrukeetStreaming {
this.audioBytesSent += buffer.length;
}
- sendControl(message) {
+ sendControl(message, onSent) {
try {
if (!this.isConnected || this.ws.readyState !== WebSocket.OPEN) {
throw new Error("Orukeet connection closed before completion");
}
- this.ws.send(JSON.stringify(message));
+ this.ws.send(JSON.stringify(message), onSent);
} catch (error) {
this.fail(error);
}
@@ -240,16 +299,21 @@ class OrukeetStreaming {
this.finalPromise = new Promise((resolve, reject) => {
this.finalResolve = resolve;
this.finalReject = reject;
- this.finalTimer = setTimeout(
- () => this.fail(new Error("Orukeet final transcript timed out")),
- this.timeoutMs
- );
- this.sendControl({ type: "commit" });
+ const timedOut = () => this.fail(new Error("Orukeet final transcript timed out"));
+ const audioSeconds = this.audioBytesSent / BYTES_PER_SECOND;
+ // The commit queues behind audio still uploading, so the scaled deadline
+ // starts once it is written; the cap bounds a slow upload.
+ this.finalCapTimer = setTimeout(timedOut, MAX_FINAL_WAIT_MS);
+ this.sendControl({ type: "commit" }, (error) => {
+ if (error || !this.finalResolve) return;
+ this.finalTimer = setTimeout(timedOut, this.finalTimeoutMs(audioSeconds));
+ });
});
return this.finalPromise;
}
clearFinal() {
+ clearTimeout(this.finalCapTimer);
clearTimeout(this.finalTimer);
clearTimeout(this.retryTimer);
this.finalResolve = this.finalReject = null;
@@ -279,11 +343,15 @@ class OrukeetStreaming {
if (this.intentionalClose) return;
this.intentionalClose = true;
clearInterval(this.keepAlive);
+ clearInterval(this.livenessTimer);
this.isConnected = false;
this.connecting = false;
this.pendingAudio = [];
this.pendingBytes = 0;
- this.ws?.close();
+ // A failed socket has nothing left to say, and a graceful close would wait
+ // behind unsent audio for up to 30 s while the account's socket slot stays taken.
+ if (this.failure) this.ws?.terminate();
+ else this.ws?.close();
this.onClose?.();
}
@@ -304,4 +372,4 @@ class OrukeetStreaming {
}
}
-module.exports = { OrukeetStreaming, streamingUrl };
+module.exports = { OrukeetStreaming, streamingUrl, MANAGED_STREAM_OPTIONS };
diff --git a/test/helpers/orukeetDictationIpc.test.js b/test/helpers/orukeetDictationIpc.test.js
index 44bc24d8a..eeef716b0 100644
--- a/test/helpers/orukeetDictationIpc.test.js
+++ b/test/helpers/orukeetDictationIpc.test.js
@@ -27,7 +27,8 @@ const cloudSession = {
};
const { once, EventEmitter } = require("node:events");
const { WebSocket, WebSocketServer } = require("ws");
-const { OrukeetStreaming } = require("../../src/helpers/orukeetStreaming");
+const orukeetStreamingModule = require("../../src/helpers/orukeetStreaming");
+const { OrukeetStreaming, MANAGED_STREAM_OPTIONS } = orukeetStreamingModule;
const AgentStreamRequestRegistry = require("../../src/helpers/agentStreamRequestRegistry");
let server,
target,
@@ -103,6 +104,7 @@ Module._load = function loadWithMocks(request, parent, isMain) {
if (parent?.filename === handlersModulePath) {
if (request === "./orukeetStreaming")
return {
+ ...orukeetStreamingModule,
OrukeetStreaming: class extends OrukeetStreaming {
constructor(options) {
super({
@@ -253,6 +255,8 @@ test(
true
);
const streaming = target._dictationStreaming;
+ assert.equal(streaming.livenessMs, MANAGED_STREAM_OPTIONS.livenessMs);
+ assert.equal(streaming.finalTimeoutMs, MANAGED_STREAM_OPTIONS.finalTimeoutMs);
const closed = once(streaming.ws, "close");
handlers.get("dictation-realtime-send")(event, Buffer.alloc(640));
const final = await handlers.get("dictation-realtime-finalize")();
@@ -285,6 +289,7 @@ test("self-hosted IPC still retries a capacity-refused commit without re-uploadi
baseUrl: cloudSession.baseUrl,
});
assert.equal(start.success, true);
+ assert.equal(target._dictationStreaming.livenessMs, null, "self-hosted servers are never pinged");
handlers.get("dictation-realtime-send")(event, Buffer.alloc(640));
const final = await handlers.get("dictation-realtime-finalize")();
diff --git a/test/helpers/orukeetStreaming.test.js b/test/helpers/orukeetStreaming.test.js
index 85e3cbf19..db22d6e4a 100644
--- a/test/helpers/orukeetStreaming.test.js
+++ b/test/helpers/orukeetStreaming.test.js
@@ -1,16 +1,22 @@
const test = require("node:test");
const assert = require("node:assert/strict");
-const { once } = require("node:events");
-const { WebSocketServer } = require("ws");
-const { OrukeetStreaming, streamingUrl } = require("../../src/helpers/orukeetStreaming");
+const { EventEmitter, once } = require("node:events");
+const { Worker } = require("node:worker_threads");
+const { WebSocket, WebSocketServer } = require("ws");
+const {
+ OrukeetStreaming,
+ streamingUrl,
+ MANAGED_STREAM_OPTIONS,
+} = require("../../src/helpers/orukeetStreaming");
-async function fixture(t, onMessage) {
- const server = new WebSocketServer({ port: 0, host: "127.0.0.1" });
+async function fixture(t, onMessage, { serverOptions, adapterOptions, onConnection } = {}) {
+ const server = new WebSocketServer({ port: 0, host: "127.0.0.1", ...serverOptions });
await once(server, "listening");
const seen = [];
server.on("connection", (socket, request) => {
assert.equal(request.headers.authorization, "Bearer test-key");
assert.equal(request.url, "/v1/audio/transcriptions/stream");
+ onConnection?.(socket);
socket.send(
JSON.stringify({
type: "ready",
@@ -26,7 +32,7 @@ async function fixture(t, onMessage) {
onMessage?.(socket, event, seen);
});
});
- const adapter = new OrukeetStreaming({ timeoutMs: 300 });
+ const adapter = new OrukeetStreaming({ timeoutMs: 300, ...adapterOptions });
t.after(async () => {
await adapter.disconnect();
for (const socket of server.clients) socket.terminate();
@@ -167,7 +173,10 @@ test("missing final acknowledgement has a bounded timeout", async (t) => {
const { adapter, options } = await fixture(t);
await adapter.connect(options);
adapter.sendAudio(Buffer.alloc(640));
+ const started = performance.now();
await assert.rejects(adapter.finalize(), /timed out/);
+ // Self-hosted streams wait their connect timeout (300 ms here) for a final.
+ assert.ok(performance.now() - started < 1000);
});
test("URL normalization retains the selected server and refuses unsafe credential URLs", () => {
@@ -311,3 +320,307 @@ test("a failure while the session token is minted raises no stream error", async
);
assert.deepEqual(errors, []);
});
+
+// Answers pings until the test stalls it, like a GPU host whose server process
+// wedges while its TCP connection stays open.
+async function stallableFixture(t, onMessage, adapterOptions) {
+ const control = { answering: true, delayMs: 0, socket: null };
+ const setup = await fixture(t, onMessage, {
+ serverOptions: { autoPong: false },
+ adapterOptions,
+ onConnection: (socket) => {
+ control.socket = socket;
+ socket.on("ping", (data) => {
+ if (!control.answering) return;
+ if (control.delayMs) setTimeout(() => socket.pong(data), control.delayMs);
+ else socket.pong(data);
+ });
+ },
+ });
+ return { ...setup, control };
+}
+
+test(
+ "a stream whose server stops answering pings fails while recording",
+ { timeout: 2000 },
+ async (t) => {
+ const livenessMs = 400;
+ const { adapter, options, control } = await stallableFixture(t, undefined, { livenessMs });
+ const raised = new Promise((resolve) => {
+ adapter.onError = resolve;
+ });
+ await adapter.connect(options);
+ await once(adapter.ws, "pong");
+ const closed = once(control.socket, "close");
+ control.answering = false;
+ const stalledAt = performance.now();
+ adapter.sendAudio(Buffer.alloc(640));
+
+ assert.match((await raised).message, /stopped responding/);
+ const detectedAfter = performance.now() - stalledAt;
+ assert.ok(
+ detectedAfter > livenessMs - 20 && detectedAfter < livenessMs * 2,
+ `${detectedAfter}`
+ );
+ await assert.rejects(adapter.finalize(), /stopped responding/);
+ // Dropped rather than closed behind unsent audio, so the server sees 1006.
+ assert.equal((await closed)[0], 1006);
+ }
+);
+
+test("a blocked main thread is not judged a stalled server", { timeout: 5000 }, async (t) => {
+ const livenessMs = 400;
+ const { adapter, options, control } = await stallableFixture(
+ t,
+ (socket, event) => {
+ if (event.type === "commit") socket.send(JSON.stringify({ type: "final", text: "Kept." }));
+ },
+ { livenessMs }
+ );
+ const errors = [];
+ adapter.onError = (error) => errors.push(error);
+ await adapter.connect(options);
+ await new Promise((resolve) =>
+ adapter.ws.once("pong", () => {
+ // The ping sent after the block is answered later than one check
+ // interval, but within the liveness window.
+ control.delayMs = livenessMs * 0.75;
+ const until = performance.now() + livenessMs * 2.5;
+ while (performance.now() < until);
+ resolve();
+ })
+ );
+ adapter.sendAudio(Buffer.alloc(640));
+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 1.5));
+
+ assert.deepEqual(errors, []);
+ assert.equal((await adapter.finalize()).text, "Kept.");
+});
+
+// Runs the server on its own thread, so it answers while the test blocks the
+// main thread. Each ping is reported to the main thread before its pong.
+async function threadedServer(t, pongDelayMs) {
+ const worker = new Worker(
+ `
+ const { parentPort } = require("node:worker_threads");
+ const { WebSocketServer } = require(${JSON.stringify(require.resolve("ws"))});
+ const server = new WebSocketServer({ port: 0, host: "127.0.0.1", autoPong: false });
+ server.on("listening", () => parentPort.postMessage(server.address().port));
+ server.on("connection", (socket) => {
+ socket.on("ping", (data) => {
+ parentPort.postMessage("ping");
+ setTimeout(() => socket.pong(data), ${pongDelayMs});
+ });
+ socket.send(
+ JSON.stringify({
+ type: "ready",
+ sample_rate: 16000,
+ channels: 1,
+ encoding: "pcm_s16le",
+ max_seconds: 60,
+ })
+ );
+ });
+ `,
+ { eval: true }
+ );
+ t.after(() => worker.terminate());
+ const [port] = await once(worker, "message");
+ return { worker, options: { baseUrl: `http://127.0.0.1:${port}`, apiKey: "test-key" } };
+}
+
+test(
+ "a pong that arrived while the main thread was blocked counts",
+ { timeout: 5000 },
+ async (t) => {
+ const { worker, options } = await threadedServer(t, 20);
+ const livenessMs = 1000;
+ const adapter = new OrukeetStreaming({ timeoutMs: 1000, livenessMs });
+ t.after(() => adapter.disconnect());
+ const errors = [];
+ adapter.onError = (error) => errors.push(error);
+ await adapter.connect(options);
+ await once(adapter.ws, "pong");
+ let pinged = false;
+ const ping = adapter.ws.ping.bind(adapter.ws);
+ adapter.ws.ping = () => {
+ ping();
+ adapter.ws.ping = ping;
+ pinged = true;
+ };
+ worker.on("message", () => {
+ if (!pinged) return;
+ pinged = false;
+ // Blocks until just past the next check's due time, so that check is on
+ // time while the pong waiting on the socket is its only sign of life.
+ const until = performance.now() + livenessMs * 0.65;
+ while (performance.now() < until);
+ });
+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 1.5));
+
+ assert.deepEqual(errors, []);
+ }
+);
+
+test("any server message keeps an armed stream alive", { timeout: 2000 }, async (t) => {
+ const livenessMs = 200;
+ const { adapter, options, control } = await stallableFixture(t, undefined, { livenessMs });
+ const errors = [];
+ adapter.onError = (error) => errors.push(error);
+ await adapter.connect(options);
+ await once(adapter.ws, "pong");
+ control.answering = false;
+ const language = JSON.stringify({ type: "language", language: "en", language_confidence: 0.9 });
+ const chatter = setInterval(() => control.socket.send(language), livenessMs / 4);
+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 3));
+ clearInterval(chatter);
+
+ assert.deepEqual(errors, []);
+});
+
+test("a server that never answers pings is not judged stalled", { timeout: 2000 }, async (t) => {
+ const { adapter, options, control } = await stallableFixture(
+ t,
+ (socket, event) => {
+ if (event.type === "commit") socket.send(JSON.stringify({ type: "final", text: "Kept." }));
+ },
+ { livenessMs: 50 }
+ );
+ control.answering = false;
+ await adapter.connect(options);
+ adapter.sendAudio(Buffer.alloc(640));
+ await new Promise((resolve) => setTimeout(resolve, 200));
+
+ assert.equal((await adapter.finalize()).text, "Kept.");
+});
+
+test(
+ "a commit awaiting its final is bounded by the final deadline, not liveness",
+ { timeout: 2000 },
+ async (t) => {
+ const { adapter, options, control } = await stallableFixture(
+ t,
+ (socket, event) => {
+ if (event.type !== "commit") return;
+ // Inference can hold the server's event loop, so pongs stop meanwhile.
+ control.answering = false;
+ setTimeout(() => socket.send(JSON.stringify({ type: "final", text: "Slow." })), 200);
+ },
+ { livenessMs: 50, timeoutMs: 1000 }
+ );
+ await adapter.connect(options);
+ await once(adapter.ws, "pong");
+ adapter.sendAudio(Buffer.alloc(640));
+
+ assert.equal((await adapter.finalize()).text, "Slow.");
+ }
+);
+
+test("a closed stream stops checking liveness", { timeout: 2000 }, async (t) => {
+ const { adapter, options } = await stallableFixture(t, undefined, { livenessMs: 50 });
+ const errors = [];
+ adapter.onError = (error) => errors.push(error);
+ await adapter.connect(options);
+ await once(adapter.ws, "pong");
+ await adapter.disconnect();
+ await new Promise((resolve) => setTimeout(resolve, 200));
+
+ assert.deepEqual(errors, []);
+});
+
+// A ready socket whose writes complete only when the test says so, like an
+// uplink still draining audio queued ahead of the commit.
+async function heldSocketAdapter(t, adapterOptions) {
+ const socket = Object.assign(new EventEmitter(), {
+ readyState: WebSocket.OPEN,
+ bufferedAmount: 0,
+ writes: [],
+ send: (data, onSent) => socket.writes.push({ data, onSent }),
+ close: () => {},
+ terminate: () => {},
+ });
+ const adapter = new OrukeetStreaming({ createSocket: () => socket, ...adapterOptions });
+ t.after(() => adapter.disconnect());
+ const connected = adapter.connect({ baseUrl: "https://orukeet.test", apiKey: "test-key" });
+ socket.emit(
+ "message",
+ JSON.stringify({
+ type: "ready",
+ sample_rate: 16000,
+ channels: 1,
+ encoding: "pcm_s16le",
+ max_seconds: 60,
+ })
+ );
+ await connected;
+ const writeCommit = () => {
+ const commit = socket.writes.at(-1);
+ assert.equal(JSON.parse(commit.data).type, "commit");
+ commit.onSent();
+ };
+ return { adapter, socket, writeCommit };
+}
+
+test(
+ "the final deadline scales with the audio and starts once the commit is written",
+ { timeout: 2000 },
+ async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ const { adapter, writeCommit } = await heldSocketAdapter(t, {
+ finalTimeoutMs: (audioSeconds) => audioSeconds * 1000,
+ });
+ adapter.sendAudio(Buffer.alloc(64000)); // 2 s of 16 kHz PCM16
+ const final = adapter.finalize();
+ final.catch(() => {});
+
+ t.mock.timers.tick(10000);
+ assert.equal(adapter.failure, undefined);
+ writeCommit();
+ t.mock.timers.tick(1999);
+ assert.equal(adapter.failure, undefined);
+ t.mock.timers.tick(1);
+ await assert.rejects(final, /final transcript timed out/);
+ }
+);
+
+test(
+ "a commit that is never written out still times out after 30 s",
+ { timeout: 2000 },
+ async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ const { adapter } = await heldSocketAdapter(t, { finalTimeoutMs: () => 1000 });
+ adapter.sendAudio(Buffer.alloc(640));
+ const final = adapter.finalize();
+ final.catch(() => {});
+
+ t.mock.timers.tick(29999);
+ assert.equal(adapter.failure, undefined);
+ t.mock.timers.tick(1);
+ await assert.rejects(final, /final transcript timed out/);
+ }
+);
+
+test("a delivered final clears the 30 s cap", { timeout: 2000 }, async (t) => {
+ t.mock.timers.enable({ apis: ["setTimeout"] });
+ const { adapter, socket, writeCommit } = await heldSocketAdapter(t, {
+ finalTimeoutMs: () => 1000,
+ });
+ let closed = false;
+ adapter.onClose = () => (closed = true);
+ adapter.sendAudio(Buffer.alloc(640));
+ const final = adapter.finalize();
+ writeCommit();
+ socket.emit("message", JSON.stringify({ type: "final", text: "Done." }));
+ assert.equal((await final).text, "Done.");
+
+ t.mock.timers.tick(30000);
+ assert.equal(closed, false);
+});
+
+test("managed streams fail over within seconds instead of the 30 s budget", () => {
+ assert.equal(MANAGED_STREAM_OPTIONS.retryCapacity, false);
+ assert.equal(MANAGED_STREAM_OPTIONS.livenessMs, 8000);
+ assert.equal(MANAGED_STREAM_OPTIONS.timeoutMs, 10000);
+ assert.equal(MANAGED_STREAM_OPTIONS.finalTimeoutMs(0), 5000);
+ assert.equal(MANAGED_STREAM_OPTIONS.finalTimeoutMs(60), 11000);
+});