Public: anyone can read this; the crew can change it.

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

src/camera-socket.ts fans one JPEG source out to many sockets, latest frame wins - a pure module with tests, no route #142

Merged opened this

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

smith/arm:smith/138-src-camera-socket-ts-fans-one-jpeg-sourc → main 4 commits fork 2 threads · 2 unresolved

  • Merged. smith/138-src-camera-socket-ts-fans-one-jpeg-sourc was merged into main as 8ca26ab.

Review

Sign in to review this change.
2 files changed +193 −0
Software/so101/src/camera-socket.test.ts added +124
@@ -0,0 +1,124 @@
1 import { describe, expect, test } from "bun:test";
2 import { CameraSocket, isWholeJpeg, MAX_FRAME, type ViewerSocket } from "./camera-socket.ts";
3
4 const jpeg = (n: number) => Buffer.from(`\xff\xd8frame-${n}\xff\xd9`, "latin1");
5 const label = (b: Uint8Array) => Buffer.from(b).toString("latin1").slice(2, -2);
6
7 /** A socket whose buffer is held full until `flush()`. */
8 function fakeSocket(stuck = false) {
9 const sent: Uint8Array[] = [];
10 let buffered = 0;
11 const ws: ViewerSocket & { sent: Uint8Array[]; flush(): void; stick(): void } = {
12 sent,
13 send(data) {
14 sent.push(data);
15 if (stuck) buffered = data.length;
16 },
17 getBufferedAmount: () => buffered,
18 flush() {
19 buffered = 0;
20 stuck = false;
21 },
22 stick() {
23 stuck = true;
24 },
25 };
26 return ws;
27 }
28
29 describe("camera-socket", () => {
30 test("every frame reaches a fast viewer, whole, as one message each", () => {
31 const hub = new CameraSocket();
32 const ws = fakeSocket();
33 hub.add(ws);
34 for (let i = 0; i < 5; i++) hub.push(jpeg(i));
35 expect(ws.sent.map(label)).toEqual(["frame-0", "frame-1", "frame-2", "frame-3", "frame-4"]);
36 });
37
38 test("a slow viewer skips to the newest frame without slowing a fast one", () => {
39 const hub = new CameraSocket();
40 const fast = fakeSocket();
41 const slow = fakeSocket(true);
42 hub.add(fast);
43 hub.add(slow);
44 for (let i = 0; i < 10; i++) hub.push(jpeg(i));
45 expect(fast.sent).toHaveLength(10);
46 expect(slow.sent.map(label)).toEqual(["frame-0"]);
47 slow.flush();
48 hub.drain(slow);
49 expect(slow.sent.map(label)).toEqual(["frame-0", "frame-9"]);
50 hub.drain(slow);
51 expect(slow.sent).toHaveLength(2);
52 });
53
54 test("a viewer joining mid-stream gets only whole JPEGs, starting with the latest", () => {
55 const hub = new CameraSocket();
56 hub.push(jpeg(1));
57 hub.push(Buffer.from([0xff, 0xd8, 1, 2, 3])); // cut short: ignored
58 hub.push(Buffer.from([1, 2, 0xff, 0xd9])); // no start: ignored
59 const late = fakeSocket();
60 hub.add(late);
61 hub.push(jpeg(2));
62 expect(late.sent.map(label)).toEqual(["frame-1", "frame-2"]);
63 expect(late.sent.every(isWholeJpeg)).toBe(true);
64 });
65
66 test("memory per viewer stays at one frame", () => {
67 const hub = new CameraSocket();
68 const slow = fakeSocket(true);
69 hub.add(slow);
70 const frames = Array.from({ length: 1000 }, (_, i) => jpeg(i));
71 for (const f of frames) hub.push(f);
72 // one sent, one pending: the pending one is the newest, the 998 between were dropped
73 slow.flush();
74 hub.drain(slow);
75 expect(slow.sent).toHaveLength(2);
76 expect(slow.sent[1]).toBe(frames[999]!);
77 });
78
79 test("a removed or failing socket is let go", () => {
80 const hub = new CameraSocket();
81 const gone = fakeSocket();
82 const bad: ViewerSocket = { send: () => { throw new Error("closed"); }, getBufferedAmount: () => 0 };
83 hub.add(gone);
84 hub.add(bad);
85 hub.push(jpeg(1));
86 expect(hub.size).toBe(1);
87 hub.remove(gone);
88 expect(hub.size).toBe(0);
89 });
90
91 test("an oversize or malformed frame is refused; a good one is taken", () => {
92 const hub = new CameraSocket();
93 const live = fakeSocket();
94 hub.add(live);
95 const big = Buffer.alloc(MAX_FRAME + 1, 1);
96 big[0] = 0xff; big[1] = 0xd8; big[big.length - 2] = 0xff; big[big.length - 1] = 0xd9;
97 expect(isWholeJpeg(big)).toBe(false);
98 expect(hub.push(big)).toBe(false);
99 expect(hub.push(Buffer.from([0xff, 0xd8, 0xff]))).toBe(false);
100 expect(hub.push(new Uint8Array(0))).toBe(false);
101 expect(live.sent).toHaveLength(0);
102 const late = fakeSocket();
103 hub.add(late);
104 expect(late.sent).toHaveLength(0);

Push the exactly-MAX_FRAME frame through a viewer too (hub.push(atLimit) returns true), not only isWholeJpeg, so the boundary is pinned end to end.

105 const atLimit = Buffer.alloc(MAX_FRAME, 1);
106 atLimit[0] = 0xff; atLimit[1] = 0xd8; atLimit[MAX_FRAME - 2] = 0xff; atLimit[MAX_FRAME - 1] = 0xd9;
107 expect(isWholeJpeg(atLimit)).toBe(true);
108 expect(hub.push(jpeg(1))).toBe(true);
109 expect(live.sent.map(label)).toEqual(["frame-1"]);
110 expect(late.sent.map(label)).toEqual(["frame-1"]);
111 });
112
113 test("adding a socket twice keeps its pending frame", () => {
114 const hub = new CameraSocket();
115 const slow = fakeSocket(true);
116 hub.add(slow);
117 hub.push(jpeg(1));
118 hub.push(jpeg(2));
119 hub.add(slow);
120 slow.flush();
121 hub.drain(slow);
122 expect(slow.sent.map(label)).toEqual(["frame-1", "frame-2"]);
123 });
124 });
Software/so101/src/camera-socket.ts added +69
@@ -0,0 +1,69 @@
1 /**
2 * One JPEG source fanned out to many WebSockets, latest frame wins. A frame is one whole JPEG, sent as one binary
3 * message. A viewer holds at most one pending frame: while its socket is still sending the last one, each newer
4 * frame replaces the pending one, so a slow viewer skips ahead and nothing is queued. Viewers do not wait on each
5 * other. The owner calls `drain(ws)` from the socket's drain event to release the pending frame.
6 */
7
8 export interface ViewerSocket {
9 send(data: Uint8Array): unknown;
10 /** Bytes accepted but not yet on the wire; 0 when the socket is ready for another frame. */
11 getBufferedAmount(): number;
12 }
13
14 /** The most bytes of one frame taken; anything bigger is not a camera frame. */
15 export const MAX_FRAME = 4 * 1024 * 1024;

MAX_FRAME is enforced in isWholeJpeg but no test fails if the check is removed. Add an oversize-frame test (and assert push() return values).

16
17 /** True for a whole JPEG: starts with SOI (FF D8), ends with EOI (FF D9), within the size limit. */
18 export function isWholeJpeg(frame: Uint8Array): boolean {
19 const n = frame.length;
20 return n >= 4 && n <= MAX_FRAME && frame[0] === 0xff && frame[1] === 0xd8 && frame[n - 2] === 0xff && frame[n - 1] === 0xd9;
21 }
22
23 export class CameraSocket {
24 /** Each viewer's pending frame, or null when it has none. */
25 private readonly viewers = new Map<ViewerSocket, Uint8Array | null>();
26 private latest: Uint8Array | null = null;
27
28 get size(): number {
29 return this.viewers.size;
30 }
31
32 /** A viewer joins; it is sent the latest whole frame at once, if there is one, and every frame after. */
33 add(ws: ViewerSocket): void {
34 if (this.viewers.has(ws)) return;
35 this.viewers.set(ws, null);
36 if (this.latest) this.offer(ws, this.latest);
37 }
38
39 remove(ws: ViewerSocket): void {
40 this.viewers.delete(ws);
41 }
42
43 /** A frame from the source. Anything that is not a whole JPEG is ignored. Returns whether it was taken. */
44 push(frame: Uint8Array): boolean {
45 if (!isWholeJpeg(frame)) return false;
46 this.latest = frame;
47 for (const ws of this.viewers.keys()) this.offer(ws, frame);
48 return true;
49 }
50
51 /** The viewer's socket has room again: send the frame it was holding, if any. */
52 drain(ws: ViewerSocket): void {
53 const pending = this.viewers.get(ws);
54 if (pending) this.offer(ws, pending);
55 }
56
57 private offer(ws: ViewerSocket, frame: Uint8Array): void {
58 try {
59 if (ws.getBufferedAmount() > 0) {
60 this.viewers.set(ws, frame);
61 return;
62 }
63 this.viewers.set(ws, null);
64 ws.send(frame);
65 } catch {
66 this.viewers.delete(ws);
67 }
68 }
69 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs