Skip to content

v0.2.0 — Complete hybrid P2P-CDN middleware

Choose a tag to compare

View all tags
@mytrashcan mytrashcan released this 17 Jul 03:19
· 118 commits to main since this release
v0.2.0
caef9e5
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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:

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

Assets 2
Loading