fix(server): Fastify 5 modernisation, fetch polyfill removal, and test coverage

[LucasMaupin]

Summary

Code review improvements addressing Fastify 5 modernisation, fetch polyfill removal, SMB resilience, comprehensive test coverage, a full demo UI redesign, SFU session reliability fixes, Fastify 5 startup-conflict resolution, SDK test suite repair, wrtc lazy-loading, null-safety hardening, lerna v9 migration to npm workspaces, and OSC deployment tooling.

Changes

Fastify 5 modernisation (packages/server/)

• Converted whipFastifyApi.ts to async plugin signature (Fastify 5 requirement)
• onRequest hook uses async/throw instead of the legacy done() callback
• Migrated from fastify-cors to @fastify/cors v10 (ES6 import)
• Updated server.listen() to the Fastify 5 object-options API
• Removed duplicate application/sdp and application/trickle-ice-sdpfrag content-type parsers from whipFastifyApi plugin — they are already registered at root level in whipEndpoint.ts; duplicates caused FST_ERR_DUPLICATED_ROUTE on startup
• Removed explicit HEAD route handlers — Fastify 5 auto-registers HEAD for every GET route; duplicate handlers caused FST_ERR_DUPLICATED_ROUTE on startup
• SDP content-type parsers moved to the root server level so all routes receive them

Fetch polyfill removal (packages/server/)

• Removed node-fetch and cross-fetch dependencies entirely
• All HTTP calls now use Node 18 native fetch
• Removed unused node-fetch import from broadcasterClient.ts and cross-fetch import from resourceManagerClient.ts
• Added undici-types devDependency (required for accurate @types/node v20 fetch typings)

ISmbProtocol interface + SMB resilience (packages/server/)

• New src/smb/ISmbProtocol.ts — interface for dependency injection and test mocking
• SmbProtocol now implements ISmbProtocol; sfuWhipResource.ts uses the interface type, not the concrete class
• withRetry() exponential back-off wrapper added to all SmbProtocol methods (5 attempts: 1 / 2 / 4 / 8 / 16 s)
• getEndpoints() and deleteEndpoint() now throw on non-OK HTTP responses (were silently swallowing errors)

SFU session reliability fixes (packages/server/src/whip/sfu/sfuWhipResource.ts)

• checkChannelHealth() now starts with a 15 s initial delay — previously it was called immediately, causing sessions to be torn down before ICE could connect (ICE state is naturally 'FAILED' at t=0)
• destroy() now wraps all SFU API calls in try/catch — DELETE no longer returns 500 when the SFU has already cleaned up the session
• forEach + async callback replaced with for..of for correct error propagation
• Null-safe optional chaining on all .at(0) SSRC/RTP lookups; skip media sections with no ssrcs to prevent runtime crashes on unexpected SDP shapes

wrtc lazy-loading + test isolation (packages/server/)

• Replaced static import { RTCPeerConnection } from "@koush/wrtc" with a dynamic require() inside the constructor, guarded behind the pcFactory branch — native binary is never loaded when a mock is injected
• pcFactory parameter added to WrtcWhipResource, RtspWrtcWhipResource, and RtmpWrtcWhipResource constructors; all three test subclasses updated to pass a factory
• spec/hooks.ts Mocha root hooks file added — silences console.log during tests to prevent SDP/ICE payloads from polluting terminal output
• timeout-minutes: 10 added to the unit-tests CI job

SDK fixes (packages/sdk/)

• Null-safe guard on RegExp.exec() return value in util.ts
• 'connectionfailed' event now emitted before destroy() so callers can react to peer-connection failure without polling
• Verbose SDP log removed from sendOffer()
• typedoc upgraded to 0.28.x for TypeScript 5 compatibility

SDK test suite fix

• Replaced Karma browser runner with mocha + ts-node (same pattern as the server package)
• Root cause: karma-typescript 5.5.4 fails to bundle CommonJS modules when TypeScript target is "esnext" — 0 tests ran in Chrome Headless
• spec/setup.js stubs RTCSessionDescription, RTCPeerConnection, MediaStream, and MediaStreamTrack so ts-mockito can mock them in Node.js
• Result: 6/6 WHIPClient tests now pass (was 0)

Demo UI redesign + refinements (packages/demo/)

Complete replacement of the new.css classless-framework UI with a custom dark-themed interface:

• Sidebar layout — 300 px left panel (Connection + Capture cards) with video preview and Active Resources section in the main area (later relocated to sidebar)
• Status pill — Idle / Connecting… / Live states with animated dot indicator in the header
• Share button — copies the shareable endpoint URL to the clipboard via navigator.clipboard
• Video placeholder — overlay icon + hint text, hidden automatically once a stream starts; position: absolute prevents video from expanding the content area; video controls shown only while streaming
• Resource cards — live dot, monospace URL, extension links with rel badges, Delete button
• Toast notifications — slide-up messages; persistent actionable toasts (480 px wide) for connectionfailed with a Reconnect action
• Reconnect UI — 'connectionfailed' handled by cleaning up card/status and offering a Reconnect button that re-acquires media and creates a new WHIPClient
• Active Resources relocated to sidebar below Capture card
• Self-contained CSS — removes CDN dependencies; uses system font stack with CSS custom properties
• input:not([type]) selector added alongside input[type="text"] to survive Parcel HTML minification (strips redundant type=text attributes in production builds)
• Responsive — collapses to single-column below 760 px

OSC deployment tooling (packages/demo/)

• packages/demo/server.js — lightweight static file server for OSC/cloud deployments
• npm run start script added to packages/demo/package.json for serving the built demo
• Root package.json start script reverted to lerna orchestration (was temporarily changed to npm workspaces start)

Lerna v9 / npm workspaces migration

• lerna bootstrap postinstall script removed (dropped in lerna v7, incompatible with v9)
• npm workspaces field added to root package.json so npm ci hoists sub-package deps (including mocha) into root node_modules
• lerna bumped to 9.0.5, fast-xml-parser bumped to 4.5.4
• @types/node bumped to ^22.0.0 at the root — required for TypeScript 5 compatibility when hoisted via workspaces (the previous @types/node@17 is incompatible with TS5's generic Uint8Array)

Dependency updates (packages/server/)

Package	Change
fastify	^3.27.4 → ^5.8.1
typescript	^4.6.2 → ^5.9.3
@fastify/cors	added ^10.1.0
@types/node	added ^20.19.37
undici-types	added (devDep)
fastify-cors	removed
node-fetch	removed
cross-fetch	removed

CI (packages/server/)

All 4 GitHub Actions workflow files updated from actions/*@v1/@v2 to @v4.

Merged dependabot PRs

The following security/maintenance PRs were merged into this branch:

PR	Package(s)	Scope
#146	brace-expansion	server
#147	pbkdf2 3.1.2 → 3.1.5	sdk
#148	serialize-javascript, mocha	server
#149	base-x 3.0.9 → 3.0.11	demo
#150	sha.js 2.4.11 → 2.4.12	sdk
#151	cipher-base 1.0.4 → 1.0.7	sdk
#153	tmp 0.2.1 → 0.2.5	sdk
#154	lodash 4.17.21 → 4.17.23	root / sdk / server
#156	semver	server
#157	qs, body-parser	sdk
#158	ajv, fastify	server
#159	tar, @mapbox/node-pre-gyp	server
#161	lerna 8 → 9.0.5	root
#162	fast-xml-parser	root

Test plan

• cd packages/server && npm test — all 66 server tests pass
• cd packages/sdk && npm test — all 6 WHIPClient tests pass (mocha + ts-node)
• cd packages/server && npm run build — TypeScript compiles cleanly
• Start server — no FST_ERR_DUPLICATED_ROUTE errors on startup
• npm ci at repo root installs cleanly via npm workspaces (mocha hoisted to root node_modules)
• cd packages/demo && npm run dev — demo loads at http://localhost:1234 with new dark UI
• Click Camera → browser prompts for permission → status pill shows Connecting… then Live
• Click Share → URL copied to clipboard toast appears
• Click Delete on a resource card → card removed, status returns to Idle when last resource gone
• Simulate connectionfailed event → persistent toast with Reconnect button appears; clicking it re-establishes the session
• Build demo with npm run build and serve with npm start — input styles render correctly (Parcel minification test)
• SFU session: establish WebRTC connection and verify health check does not tear down the session within the first 15 s
• SFU session: call destroy when SFU has already cleaned up → no 500 error returned

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com

[birme]

To big PR to be able to make a good review but I trust that it is tested and ok.