Skip to content

Commit 9c29664

Browse files
Merge pull request #3066 from davidgamero/exec-keepalive-feedback
Add optional exec websocket keepalive with lifecycle safeguards
2 parents 088cb13 + c00d4c1 commit 9c29664

2 files changed

Lines changed: 250 additions & 3 deletions

File tree

‎src/exec.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ import { KubeConfig } from './config.js';
77
import { isResizable, ResizableStream, TerminalSizeQueue } from './terminal-size-queue.js';
88
import { WebSocketHandler, WebSocketInterface } from './web-socket-handler.js';
99

10+
export interface ExecOptions {
11+
/**
12+
* Optional websocket keepalive interval in milliseconds (1 to 2147483647).
13+
* Only one ping is outstanding until a pong is received; this is not a pong timeout.
14+
* Ignored when the socket does not support ping and Node-style event listeners.
15+
*/
16+
pingIntervalMs?: number;
17+
}
18+
1019
export class Exec {
1120
public 'handler': WebSocketInterface;
1221

@@ -27,6 +36,7 @@ export class Exec {
2736
* @param {boolean} tty - Should the command execute in a TTY enabled session.
2837
* @param {(V1Status) => void} statusCallback -
2938
* A callback to received the status (e.g. exit code) from the command, optional.
39+
* @param {ExecOptions} options - Optional websocket keepalive settings.
3040
* @return {Promise<WebSocket>} A promise that will return the web socket created for this command.
3141
*/
3242
public async exec(
@@ -39,7 +49,16 @@ export class Exec {
3949
stdin: stream.Readable | null,
4050
tty: boolean,
4151
statusCallback?: (status: V1Status) => void,
52+
options?: ExecOptions,
4253
): Promise<WebSocket.WebSocket> {
54+
const pingIntervalMs = options?.pingIntervalMs;
55+
if (
56+
pingIntervalMs !== undefined &&
57+
(!Number.isInteger(pingIntervalMs) || pingIntervalMs <= 0 || pingIntervalMs > 2147483647)
58+
) {
59+
// Validate before connecting so invalid options cannot start a remote command.
60+
throw new Error('pingIntervalMs must be an integer between 1 and 2147483647');
61+
}
4362
const query = {
4463
stdout: stdout != null,
4564
stderr: stderr != null,
@@ -68,6 +87,45 @@ export class Exec {
6887
WebSocketHandler.handleStandardInput(conn, this.terminalSizeQueue, WebSocketHandler.ResizeStream);
6988
this.terminalSizeQueue.handleResizes(stdout as any as ResizableStream);
7089
}
90+
if (pingIntervalMs !== undefined) {
91+
this.setupPing(conn, pingIntervalMs);
92+
}
7193
return conn;
7294
}
95+
96+
private setupPing(conn: WebSocket.WebSocket, pingIntervalMs: number): void {
97+
if (
98+
typeof conn.ping !== 'function' ||
99+
typeof conn.on !== 'function' ||
100+
typeof conn.removeListener !== 'function' ||
101+
conn.readyState !== WebSocket.OPEN
102+
) {
103+
return;
104+
}
105+
106+
let awaitingPong = false;
107+
const onPong = () => {
108+
awaitingPong = false;
109+
};
110+
const clearKeepAlive = () => {
111+
clearInterval(timer);
112+
conn.removeListener('pong', onPong);
113+
conn.removeListener('close', clearKeepAlive);
114+
conn.removeListener('error', clearKeepAlive);
115+
};
116+
const timer = setInterval(() => {
117+
if (conn.readyState !== WebSocket.OPEN) {
118+
clearKeepAlive();
119+
return;
120+
}
121+
if (!awaitingPong) {
122+
awaitingPong = true;
123+
conn.ping();
124+
}
125+
}, pingIntervalMs);
126+
conn.on('pong', onPong);
127+
conn.on('close', clearKeepAlive);
128+
conn.on('error', clearKeepAlive);
129+
timer.unref();
130+
}
73131
}

‎src/exec_test.ts‎

Lines changed: 192 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,21 @@
1-
import { describe, it } from 'node:test';
2-
import { deepStrictEqual, strictEqual } from 'node:assert';
1+
import { beforeEach, describe, it } from 'node:test';
2+
import { deepStrictEqual, ok, rejects, strictEqual } from 'node:assert';
3+
import { EventEmitter, once } from 'node:events';
34
import WebSocket from 'isomorphic-ws';
45
import { ReadableStreamBuffer, WritableStreamBuffer } from 'stream-buffers';
56
import { anyFunction, anything, capture, instance, mock, verify, when } from 'ts-mockito';
67

78
import { CallAwaiter, matchBuffer, ResizableWriteableStreamBuffer } from './test/index.js';
89
import { V1Status } from './api.js';
910
import { KubeConfig } from './config.js';
10-
import { Exec } from './exec.js';
11+
import { Exec, ExecOptions } from './exec.js';
1112
import { TerminalSize } from './terminal-size-queue.js';
1213
import { WebSocketHandler, WebSocketInterface } from './web-socket-handler.js';
1314

1415
describe('Exec', () => {
16+
const startExec = (exec: Exec, options?: ExecOptions) =>
17+
exec.exec('ns', 'pod', 'container', 'command', null, null, null, false, undefined, options);
18+
1519
describe('basic', () => {
1620
it('should correctly exec to a url', async () => {
1721
const kc = new KubeConfig();
@@ -157,4 +161,189 @@ describe('Exec', () => {
157161
verify(fakeWebSocket.close()).called();
158162
});
159163
});
164+
165+
describe('keepalive', () => {
166+
let conn: EventEmitter & { readyState: number; ping: () => void };
167+
let pingCount: number;
168+
let connectCount: number;
169+
let exec: Exec;
170+
const start = (options?: ExecOptions) => startExec(exec, options);
171+
172+
beforeEach((t) => {
173+
ok('mock' in t);
174+
t.mock.timers.enable({ apis: ['setInterval'] });
175+
pingCount = 0;
176+
connectCount = 0;
177+
conn = Object.assign(new EventEmitter(), {
178+
readyState: WebSocket.OPEN as number,
179+
ping: () => {
180+
pingCount++;
181+
},
182+
});
183+
exec = new Exec(new KubeConfig(), {
184+
connect: async () => {
185+
connectCount++;
186+
return conn as unknown as WebSocket.WebSocket;
187+
},
188+
});
189+
});
190+
191+
it('sends one ping at a time and resumes after pong', async (t) => {
192+
await start({ pingIntervalMs: 10 });
193+
t.mock.timers.tick(9);
194+
strictEqual(pingCount, 0);
195+
t.mock.timers.tick(1);
196+
strictEqual(pingCount, 1);
197+
t.mock.timers.tick(100);
198+
strictEqual(pingCount, 1);
199+
conn.emit('pong');
200+
t.mock.timers.tick(10);
201+
strictEqual(pingCount, 2);
202+
t.mock.timers.tick(100);
203+
strictEqual(pingCount, 2);
204+
});
205+
206+
const disabledCases: { name: string; options?: ExecOptions; socket?: object }[] = [
207+
{ name: 'omitted options' },
208+
{ name: 'empty options', options: {} },
209+
{ name: 'undefined interval', options: { pingIntervalMs: undefined } },
210+
{ name: 'missing ping', socket: { ping: undefined } },
211+
{ name: 'non-function on', socket: { on: true } },
212+
{ name: 'missing removeListener', socket: { removeListener: undefined } },
213+
{ name: 'connecting socket', socket: { readyState: WebSocket.CONNECTING } },
214+
{ name: 'closing socket', socket: { readyState: WebSocket.CLOSING } },
215+
{ name: 'closed socket', socket: { readyState: WebSocket.CLOSED } },
216+
];
217+
for (const { name, options, socket } of disabledCases) {
218+
it(`keeps pings disabled for ${name}`, async (t) => {
219+
Object.assign(conn, socket);
220+
const interval = t.mock.method(globalThis, 'setInterval');
221+
await start(socket ? { pingIntervalMs: 10 } : options);
222+
t.mock.timers.tick(100);
223+
strictEqual(pingCount, 0);
224+
strictEqual(interval.mock.callCount(), 0);
225+
deepStrictEqual(conn.eventNames(), []);
226+
});
227+
}
228+
229+
for (const value of [0, -1, 1.5, NaN, Infinity, 2147483648, '10', null]) {
230+
it(`rejects invalid interval ${String(value)} before connecting`, async () => {
231+
await rejects(
232+
start({ pingIntervalMs: value as number }),
233+
/pingIntervalMs must be an integer/,
234+
);
235+
strictEqual(connectCount, 0);
236+
});
237+
}
238+
239+
for (const pingIntervalMs of [1, 2147483647]) {
240+
it(`accepts interval boundary ${pingIntervalMs}`, async (t) => {
241+
await start({ pingIntervalMs });
242+
t.mock.timers.tick(pingIntervalMs - 1);
243+
strictEqual(pingCount, 0);
244+
t.mock.timers.tick(1);
245+
strictEqual(pingCount, 1);
246+
});
247+
}
248+
249+
for (const event of ['close', 'error']) {
250+
it(`cleans up its timer and listeners on ${event}`, async (t) => {
251+
const externalListener = () => {};
252+
for (const name of ['pong', 'close', 'error']) {
253+
conn.on(name, externalListener);
254+
}
255+
const clear = t.mock.method(globalThis, 'clearInterval');
256+
await start({ pingIntervalMs: 10 });
257+
t.mock.timers.tick(10);
258+
strictEqual(pingCount, 1);
259+
conn.emit(event);
260+
strictEqual(clear.mock.callCount(), 1);
261+
for (const name of ['pong', 'close', 'error']) {
262+
deepStrictEqual(conn.listeners(name), [externalListener]);
263+
}
264+
conn.emit('pong');
265+
t.mock.timers.tick(100);
266+
strictEqual(pingCount, 1);
267+
conn.emit('close');
268+
strictEqual(clear.mock.callCount(), 1);
269+
});
270+
}
271+
272+
it('cleans up if the socket stops being open without a close event', async (t) => {
273+
await start({ pingIntervalMs: 10 });
274+
conn.readyState = WebSocket.CLOSING;
275+
const clear = t.mock.method(globalThis, 'clearInterval');
276+
t.mock.timers.tick(10);
277+
strictEqual(clear.mock.callCount(), 1);
278+
strictEqual(pingCount, 0);
279+
deepStrictEqual(conn.eventNames(), []);
280+
});
281+
282+
it('handles a synchronous pong without getting stuck', async (t) => {
283+
conn.ping = () => {
284+
pingCount++;
285+
conn.emit('pong');
286+
};
287+
await start({ pingIntervalMs: 10 });
288+
t.mock.timers.tick(10);
289+
t.mock.timers.tick(10);
290+
strictEqual(pingCount, 2);
291+
});
292+
293+
it('keeps concurrent sessions independent', async (t) => {
294+
await start({ pingIntervalMs: 10 });
295+
const firstConn = conn;
296+
conn = Object.assign(new EventEmitter(), {
297+
readyState: WebSocket.OPEN as number,
298+
ping: conn.ping,
299+
});
300+
await start({ pingIntervalMs: 10 });
301+
t.mock.timers.tick(10);
302+
strictEqual(pingCount, 2);
303+
firstConn.emit('close');
304+
conn.emit('pong');
305+
t.mock.timers.tick(10);
306+
strictEqual(pingCount, 3);
307+
strictEqual(conn.listenerCount('pong'), 1);
308+
deepStrictEqual(firstConn.eventNames(), []);
309+
});
310+
});
311+
312+
it('exchanges keepalive ping/pong frames with a real websocket', { timeout: 5000 }, async (t) => {
313+
const server = new WebSocket.Server({ port: 0 });
314+
let client: WebSocket.WebSocket | undefined;
315+
t.after(() => {
316+
client?.terminate();
317+
for (const socket of server.clients) {
318+
socket.terminate();
319+
}
320+
server.close();
321+
});
322+
await once(server, 'listening');
323+
const address = server.address();
324+
ok(typeof address === 'object' && address !== null);
325+
let pingCount = 0;
326+
server.on('connection', (socket) => {
327+
socket.on('ping', () => {
328+
pingCount++;
329+
});
330+
});
331+
const exec = new Exec(new KubeConfig(), {
332+
connect: async () => {
333+
client = new WebSocket(`ws://127.0.0.1:${address.port}`);
334+
await once(client, 'open');
335+
return client;
336+
},
337+
});
338+
const conn = await startExec(exec, { pingIntervalMs: 10 });
339+
await once(conn, 'pong');
340+
await once(conn, 'pong');
341+
strictEqual(pingCount, 2);
342+
const closed = once(conn, 'close');
343+
conn.close();
344+
await closed;
345+
strictEqual(conn.listenerCount('pong'), 0);
346+
strictEqual(conn.listenerCount('close'), 0);
347+
strictEqual(conn.listenerCount('error'), 0);
348+
});
160349
});

0 commit comments

Comments
 (0)