OpenStreamGrid 0.7.0

OpenStreamGrid 0.7.0 makes tracker signaling scale with the audience, brings
P2P offload to LL-HLS viewers and existing origins, and hardens the tracker
and peers against abusive clients. The full list is in the
changelog.

Highlights

• Signaling that scales linearly. Clients negotiate inventory_batch and
  neighbor_view: inventory updates are batched every 250 ms and each viewer
  sees a bounded set of neighbors (TRACKER_NEIGHBOR_VIEW_SIZE, default 64).
  One tracker serves 4000 peers in one broadcast at under half a core
  (Tracker capacity).
• LL-HLS. Partial segments load from the origin, and with
  assembleLowLatencySegments viewers at the live edge join a segment's parts,
  verify it, and share it (ADR 0002).
• Existing origins. origin/dist/sidecars.js writes the SHA-256 sidecars
  peers verify against for any packager's output. Node peers follow a
  multivariant playlist to one rendition (RENDITION) and skip peers on other
  renditions.
• Players. hlsJsConfig() supports players that create hls.js themselves,
  such as Video.js 10.
• Operations. Metrics for signaling traffic, event-loop delay, and refused
  requests; a Security row and event-loop panel in Grafana; an optional
  PrometheusRule; LOG_LEVEL; and --help for the peer and sidecar CLIs.

Security

• Peer addresses that are loopback, unspecified, or link-local are rejected,
  including IPv4-mapped IPv6 literals, and Node peers refuse host names that
  resolve to them.
• The tracker bounds what one peer can make it relay: peer IDs (128
  characters), addresses (2048), metadata (32 entries, 4096 characters),
  inventories (2000 segments, 128 KiB of IDs), and reported segment IDs per
  second across REST and WebSocket.
• Node peers drop HTTP uploads to clients that stop reading for 10 s.
• Tracker reconnects are jittered so an audience does not return in lockstep.

Upgrade notes

• Joins with peer IDs over 128 characters or containing whitespace, addresses
  over 2048 characters, or metadata beyond the new limits now get 400.
• REST segment reports are limited to 512 IDs of up to 512 characters, and a
  peer reporting more than 16 K ID characters per second gets 429 (REST) or
  has its WebSocket closed with 1008.
• SQLite writes from heartbeats and reports are committed once per event-loop
  turn; a crash can lose that turn's writes.
• In the SDK package, hls.js is an optional peer dependency, and the type
  declarations no longer import the unpublished @openstreamgrid/common.

Validation

• npm run build, npm run typecheck, npm run lint
• npm test across all workspaces and the SDK
• Browser E2E for hls.js (MPEG-TS, fMP4, LL-HLS parts), Shaka, and Video.js 10
• Docker multi-peer test, with one peer following the master playlist
• helm lint with the optional templates enabled

v0.6.1 — Hardening & Multi-Arch Images

OpenStreamGrid 0.6.1 is a patch release for 0.6.0. It hardens tracker
admission and signaling, fixes the WebSocket Origin allowlist for Node peers,
makes the Helm chart deployable with its default values, and publishes
multi-architecture container images. Scheduling behavior is unchanged.

Security

• Peer joins are atomic: concurrent joins can no longer exceed the
  per-broadcast peer cap or both receive session tokens, and WebSocket segment
  deltas are applied atomically in the store.
• WebSocket upgrades reserve the per-IP connection slot before the handshake
  and prefer Authorization: Bearer over the sessionToken query parameter.
• Fixed a polynomial-ReDoS in the SDK parseSha256 helper.

Fixes

• TRACKER_WS_ALLOWED_ORIGINS now applies only to browser upgrades. Node
  peers, which send no Origin header, are no longer rejected with 403 and
  still require a valid peer session. Allowlist entries are validated and
  normalized at startup.
• The Helm chart's default image tag (0.5.0) did not exist on GHCR. The chart
  now resolves images to v<appVersion>.

Upgrade notes

• If you set TRACKER_WS_ALLOWED_ORIGINS, every entry must be an http(s)
  origin such as https://player.example; other values stop the tracker at
  startup.
• The project is now licensed under MIT (previously GPL-3.0).

Operations

• Container images are built for linux/amd64 and linux/arm64, include an
  SBOM attestation, and are tagged both v0.6.1 and 0.6.1.
• CI pins every action to a commit SHA, runs on Node 22 and 24, builds the
  images on native arm64 runners, and reports test coverage.
• Added a Code of Conduct and Dependabot version updates.

Validation

• npm run build
• npm run typecheck
• npm run test:coverage (235 tests)
• npm run lint
• helm lint and helm template with default values

Container images

Component	Image
Tracker	ghcr.io/mytrashcan/openstreamgrid-tracker:v0.6.1
Origin	ghcr.io/mytrashcan/openstreamgrid-origin:v0.6.1
Node peer	ghcr.io/mytrashcan/openstreamgrid-peer:v0.6.1

Each image is also tagged 0.6.1 and supports linux/amd64 and linux/arm64.

Full Changelog: v0.6.0...v0.6.1

v0.6.0 — Deadline-Aware Scheduling

OpenStreamGrid 0.6.0 completes a three-phase scheduling program that makes
delivery decisions reproducible, extensible, and aware of playback deadlines.
The release adds a controlled QoE benchmark foundation, extracts Node and
browser scheduling behind shared contracts, and introduces deadline-aware
Origin hedging while preserving verified Origin fallback as the final safety
boundary.

Phase 1 — Reproducible Benchmarking and QoE Measurement

• Added versioned benchmark scenarios, deterministic seeded execution, JSON
  schema validation, and environment provenance for repeatable experiments.
• Expanded measurement to include request outcomes, deadline misses, stall
  proxies, latency percentiles, P2P efficiency, Origin fallback, and Jain's
  fairness index.
• Added repeated-run aggregation with confidence intervals, result comparison
  with drift warnings, self-contained SVG reports, CI execution, and a documented
  benchmark methodology.

Phase 2 — Pluggable Scheduling Core

• Added shared SegmentScheduler contracts, scheduling plans, observations,
  decision records, and exception-safe plan validation.
• Extracted the existing Node weighted-score policy and browser trust/latency
  probe policy into injectable schedulers without changing their default
  selection behavior.
• Added batch planning, decision replay, characterization coverage, structured
  scheduler warnings, and lifecycle hooks while keeping malformed or failing
  custom policies behind an immediate Origin fallback.

Phase 3 — Deadline-Aware Scheduling and Hedged Origin Requests

• Added deadline-aware scheduler decorators for Node peers and the browser SDK.
  Unknown deadlines retain legacy P2P-first behavior, relaxed deadlines allow
  peer attempts, and critical deadlines select Origin immediately.
• Derived synthetic Node deadlines and Hls.js playback deadlines, and added a
  bounded Origin-latency estimator for deciding the latest safe fallback start.
• Added first-success-wins hedged P2P/Origin execution with cancellation,
  request coalescing, abort propagation, and explicit scheduler statistics.
• Added a deterministic scheduler lab with critical, tight, relaxed,
  slow-Origin, unreliable-peer, and mixed-workload scenarios. The committed
  mixed-workload simulation reaches a 100% deadline-met rate for both
  deadline-aware policies; this is a controlled scheduler result, not a
  production capacity claim.

Validation

• npm run build
• npm run typecheck
• npm test (226 tests)
• npm run lint

The release-preparation fix also excludes nested workspace dist-test
artifacts through ESLint's flat configuration, preventing generated test output
from being linted in CI.

OpenStreamGrid v0.5.0

OpenStreamGrid 0.5.0 hardens the peer-assisted MPEG-TS HLS middleware for controlled production evaluation. Peer identity now uses signed, short-lived sessions, peer uploads are authenticated, and untrusted network inputs have explicit quotas and size limits. Origin fallback remains available throughout playback.

Highlights

• Replaced browser-visible administrator credentials with signed, identity-scoped peer sessions that expire automatically.
• Authenticated HTTP and WebRTC peer transfers and bounded REST, WebSocket, signaling, segment, and failure-report inputs.
• Added upload concurrency and bandwidth enforcement, request coalescing, deadline-aware fallback, and bounded transport buffers.
• Added origin restart backoff, immutable segment names, streaming SHA-256 sidecars, broadcast leases, and graceful registration cleanup.
• Added transactional SQLite schema migrations, stronger constraints, incremental segment updates, and retained statistics rollups.
• Corrected browser integrity accounting and urgent-segment routing while preserving WebRTC and HTTP Node-peer interoperability.
• Aligned all packages and the Helm chart at 0.5.0 and wired deployment credentials through Kubernetes Secrets.

Upgrade notes

• Configure a stable, random PEER_SESSION_SECRET of at least 32 bytes. Do not reuse TRACKER_API_KEY.
• Peer REST calls now use Authorization: Bearer <token>; WebSocket upgrades use ?sessionToken=<token>.
• Create the Kubernetes Secret referenced by tracker.auth.existingSecret before installing the Helm chart.
• Keep the SQLite tracker at one replica unless a shared external store is introduced.
• This release supports MPEG-TS HLS. LL-HLS and CMAF/fMP4 remain roadmap items.
• Use HTTPS, WSS, and authenticated TURN for internet-facing deployments.

Distribution

• Container images: ghcr.io/mytrashcan/openstreamgrid-{tracker,origin,peer}:v0.5.0
• The browser SDK is build- and package-verified but is not yet published to npm.

Validation

• Build, strict TypeScript checks, ESLint, and all 108 automated tests passed on Node.js 22.
• Production and SDK dependency audits reported zero vulnerabilities.
• Tracker, Origin, and Peer container publication completed successfully.

See the full release notes and changelog.

v0.4.1 — Security audit remediation

Security Fixes

🔴 Critical: Tracker authentication was documented but never implemented

The TRACKER_API_KEY env var existed in CORS headers and SECURITY.md since v0.3.0, but the tracker never validated it. Every REST and WebSocket endpoint was wide open.

Fix: Added constant-time API key comparison (tracker/src/api-key.ts) and middleware enforcing X-API-Key on REST POST/PUT/DELETE, stats, and dashboard SSE endpoints. WebSocket upgrades validate ?apiKey= query parameter. Backward compatible — when TRACKER_API_KEY is unset, auth is disabled (dev mode).

🟡 CI supply chain hardening

Replaced unpinned npx eslint . with npm run lint.

🟡 SDK WebSocket auth support

Browser SDK WsTrackerClient now appends ?apiKey= when configured.

---

Full audit report: Reviewed by Hermes Agent - deepseek-v4-flash

OpenStreamGrid v0.4.0

OpenStreamGrid 0.4.0 Release Notes

OpenStreamGrid 0.4.0 removes the installation barrier for viewer peers. A page
using the Hls.js SDK now registers the viewer with the tracker, advertises
verified cached segments, exchanges those segments over WebRTC DataChannels,
reports traffic, and leaves cleanly when playback ends. Origin fallback remains
active throughout the lifecycle.

Highlights

• No viewer executable or Chrome extension is required.
• Browser-to-browser uploads use WebRTC DataChannels and tracker-relayed SDP.
• Browser peers use path-qualified segment IDs so adaptive renditions remain
  isolated.
• Uploads default to 1 Mbps and three concurrent connections, both configurable.
• REST registration is retried after transient tracker failures.
• Tracker REST endpoints support browser CORS preflight requests.
• Active DataChannel transfers receive a size- and bandwidth-aware deadline.
• Browser peers continue to consume existing HTTP Node peers.
• The SDK suite includes a real two-peer DataChannel transfer test.

Upgrade

The browser peer path is enabled by default. Existing applications can opt out
with peerParticipation: false. Production deployments should provide HTTPS,
WSS, and a TURN service for restrictive NAT and firewall environments.

---

OpenStreamGrid 0.2.0 Release Notes

OpenStreamGrid 0.2.0 delivers the complete four-phase prototype for adding
hybrid P2P-CDN delivery to an existing HLS live-streaming service. It is
middleware rather than a full streaming platform: the origin produces standard
HLS, the tracker coordinates peers, and clients retrieve verified segments from
peers with an automatic origin fallback.

Architecture overview

FFmpeg -> HLS Origin -------------------------------> Player
              |                                        ^
              | register broadcast                     |
              v                                        | origin fallback
        Tracker and Control Server                     |
          | REST / WebSocket / SSE                      |
          |                                             |
          +------> Peer A <--- HTTP or WebRTC ---> Peer B
                     ^                              ^
                     | Hls.js / Node clients        |
                     +---- verified segment cache --+

• Origin server: generates low, medium, and high HLS renditions, serves
  playlists and segments, and publishes SHA-256 sidecars.
• Tracker: manages broadcasts, peers, segment availability, WebSocket
  signaling, live statistics, trust signals, and persistent SQLite state.
• Node peer: caches and uploads segments within configured bandwidth and
  concurrency limits, ranks download sources, and falls back to origin.
• Browser SDK: integrates with Hls.js and provides browser-compatible
  caching, signaling, integrity verification, and hybrid fetching.
• Operations: Docker Compose supports local multi-peer validation; Helm and
  Kustomize support Kubernetes deployment; the dashboard exposes live metrics.

Features implemented

• Standard HLS delivery with three adaptive-bitrate renditions.
• HTTP and WebRTC DataChannel P2P transports with automatic origin fallback.
• Real-time WebSocket discovery and signaling plus Server-Sent Events metrics.
• Quality-based peer ranking using latency, success rate, bandwidth, and trust.
• Parallel downloads, request coalescing, LRU caching, and SHA-256 verification.
• Upload bandwidth and concurrent connection limits.
• SQLite persistence with WAL mode, migrations, recovery, and statistics history.
• Browser SDK builds for ESM and CommonJS with an Hls.js loader plugin.
• Monitoring dashboard, structured statistics, virtual-peer load tests, and
  reproducible JSON benchmarks.
• Docker Compose, health checks, CI, Helm, Kustomize, ingress, autoscaling,
  persistent volumes, and network policies.
• End-to-end coverage for HLS generation, peer exchange, transport fallback,
  churn, and tracker restart persistence.

Quick start

Prerequisites are Docker with Compose. For local development, use Node.js 22 or
newer, npm 10 or newer, and FFmpeg.

git clone https://github.com/mytrashcan/OpenStreamGrid.git
cd OpenStreamGrid
docker compose up --build

After the services become healthy:

• HLS master playlist: http://localhost:8080/hls/stream.m3u8
• Monitoring dashboard: http://localhost:7070/dashboard
• Tracker health endpoint: http://localhost:7070/health
• Peer A health endpoint: http://localhost:9091/health
• Peer B health endpoint: http://localhost:9092/health

Run the automated local validation with:

npm install
npm install --prefix sdk
npm run build
npm run typecheck
npm test

Docker usage guide

Start the tracker, origin, and two peers in the foreground:

docker compose up --build

Start them in the background and inspect health:

docker compose up --build --detach tracker origin peer-a peer-b
docker compose ps

Run the lightweight health and MVP checks:

npm run test:docker-health
./test/docker-test.sh

Run the comprehensive Phase 4 end-to-end suite, which uses and removes an
isolated Compose project:

./scripts/e2e-test.sh

Run a reproducible ten-peer benchmark and write benchmark-results.json:

PEER_COUNT=10 DURATION_SECONDS=60 ./scripts/benchmark.sh

Stop the default stack and remove its containers and network:

docker compose down

Add --volumes only when the persisted tracker database should also be removed.

Documentation

• Project overview, API, configuration, and development guide
• Kubernetes deployment guide
• Helm chart configuration
• Docker Compose stack
• Phase 4 end-to-end test
• Benchmark runner
• Browser SDK example
• Release history

v0.3.0 — Production Hardening & Multi-Channel

What's Changed

• feat: STUN/TURN NAT traversal support by @mytrashcan in #19
• feat: auth and HTTPS/WSS support by @mytrashcan in #20
• feat: rate limiting and Prometheus monitoring by @mytrashcan in #21
• feat: performance optimization and documentation by @mytrashcan in #22
• feat: multi-broadcast channel support by @mytrashcan in #23
• chore: bump version to 0.3.0 by @mytrashcan in #24

Full Changelog: v0.2.0...v0.3.0

v0.2.0 — Complete hybrid P2P-CDN middleware

OpenStreamGrid 0.2.0 Release Notes

OpenStreamGrid 0.2.0 delivers the complete four-phase prototype for adding
hybrid P2P-CDN delivery to an existing HLS live-streaming service. It is
middleware rather than a full streaming platform: the origin produces standard
HLS, the tracker coordinates peers, and clients retrieve verified segments from
peers with an automatic origin fallback.

Architecture overview

FFmpeg -> HLS Origin -------------------------------> Player
              |                                        ^
              | register broadcast                     |
              v                                        | origin fallback
        Tracker and Control Server                     |
          | REST / WebSocket / SSE                      |
          |                                             |
          +------> Peer A <--- HTTP or WebRTC ---> Peer B
                     ^                              ^
                     | Hls.js / Node clients        |
                     +---- verified segment cache --+

• Origin server: generates low, medium, and high HLS renditions, serves
  playlists and segments, and publishes SHA-256 sidecars.
• Tracker: manages broadcasts, peers, segment availability, WebSocket
  signaling, live statistics, trust signals, and persistent SQLite state.
• Node peer: caches and uploads segments within configured bandwidth and
  concurrency limits, ranks download sources, and falls back to origin.
• Browser SDK: integrates with Hls.js and provides browser-compatible
  caching, signaling, integrity verification, and hybrid fetching.
• Operations: Docker Compose supports local multi-peer validation; Helm and
  Kustomize support Kubernetes deployment; the dashboard exposes live metrics.

Features implemented

• Standard HLS delivery with three adaptive-bitrate renditions.
• HTTP and WebRTC DataChannel P2P transports with automatic origin fallback.
• Real-time WebSocket discovery and signaling plus Server-Sent Events metrics.
• Quality-based peer ranking using latency, success rate, bandwidth, and trust.
• Parallel downloads, request coalescing, LRU caching, and SHA-256 verification.
• Upload bandwidth and concurrent connection limits.
• SQLite persistence with WAL mode, migrations, recovery, and statistics history.
• Browser SDK builds for ESM and CommonJS with an Hls.js loader plugin.
• Monitoring dashboard, structured statistics, virtual-peer load tests, and
  reproducible JSON benchmarks.
• Docker Compose, health checks, CI, Helm, Kustomize, ingress, autoscaling,
  persistent volumes, and network policies.
• End-to-end coverage for HLS generation, peer exchange, transport fallback,
  churn, and tracker restart persistence.

Quick start

Prerequisites are Docker with Compose. For local development, use Node.js 22 or
newer, npm 10 or newer, and FFmpeg.

git clone https://github.com/mytrashcan/OpenStreamGrid.git
cd OpenStreamGrid
docker compose up --build

After the services become healthy:

• HLS master playlist: http://localhost:8080/hls/stream.m3u8
• Monitoring dashboard: http://localhost:7070/dashboard
• Tracker health endpoint: http://localhost:7070/health
• Peer A health endpoint: http://localhost:9091/health
• Peer B health endpoint: http://localhost:9092/health

Run the automated local validation with:

npm install
npm install --prefix sdk
npm run build
npm run typecheck
npm test

Docker usage guide

Start the tracker, origin, and two peers in the foreground:

docker compose up --build

Start them in the background and inspect health:

docker compose up --build --detach tracker origin peer-a peer-b
docker compose ps

Run the lightweight health and MVP checks:

npm run test:docker-health
./test/docker-test.sh

Run the comprehensive Phase 4 end-to-end suite, which uses and removes an
isolated Compose project:

./scripts/e2e-test.sh

Run a reproducible ten-peer benchmark and write benchmark-results.json:

PEER_COUNT=10 DURATION_SECONDS=60 ./scripts/benchmark.sh

Stop the default stack and remove its containers and network:

docker compose down

Add --volumes only when the persisted tracker database should also be removed.

Documentation

• Project overview, API, configuration, and development guide
• Kubernetes deployment guide
• Helm chart configuration
• Docker Compose stack
• Phase 4 end-to-end test
• Benchmark runner
• Browser SDK example
• Release history