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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/138-src-camera-socket-ts-fans-one-jpeg-sourc → main 4 commits fork 2 threads · 2 unresolved
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); | |
| 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 | } |
new above
offline
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.