feat: add livestream REST endpoints by mrdarrengriffin · Pull Request #32 · OpenHomeFoundation/web-api

mrdarrengriffin · 2026-07-09T12:05:56Z

Adds a livestream endpoint that reports the YouTube livestream status for
Open Home Foundation project channels (Home Assistant, ESPHome, Open Home
Foundation, Music Assistant). Websites can call this to show upcoming, live, or
recently-ended streams.

Endpoints

GET /livestream — status for all configured channels
GET /livestream/:slug — status for a single channel (e.g. home-assistant);
returns 404 for unknown slugs

Each entry returns a status of live, upcoming, past (within 24h of
ending), or none, plus title, url, and (for upcoming) startTime.

Notes

Channels are config-driven in src/livestream/livestream.channels.ts —
adding a project is a one-line change.
Results are cached per channel (5 min TTL) with in-flight de-duplication;
a failing channel falls back to stale data and doesn't affect the others.
Requires a YOUTUBE_API_KEY (YouTube Data API v3), loaded from .env via
@nestjs/config. See .env.example.
Devcontainer now forwards port 3000 (the app's default) instead of 443.

Copilot

Pull request overview

This PR introduces a new NestJS livestream feature area that exposes REST endpoints for querying YouTube livestream state for a configured set of Open Home Foundation project channels, backed by YouTube Data API v3 and cached per channel.

Changes:

Add GET /livestream and GET /livestream/:slug endpoints via a new controller/module/service.
Implement YouTube API integration with per-channel caching and in-flight refresh de-duplication.
Wire up global config loading (@nestjs/config) and add developer/supporting files (.env.example, devcontainer port forwarding, .env gitignore).

Reviewed changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/livestream/livestream.service.ts	Implements YouTube API lookups, caching, and status derivation logic for channels.
src/livestream/livestream.controller.ts	Adds REST endpoints for listing all channel statuses and querying by slug.
src/livestream/livestream.module.ts	Registers the livestream controller/service in a dedicated Nest module.
src/livestream/livestream.channels.ts	Defines the config-driven list of tracked channels (slug/name/handle).
src/livestream/index.ts	Exposes livestream module/service/channels via barrel exports.
src/app.module.ts	Enables global config loading and registers `LivestreamModule`.
package.json	Adds `@nestjs/config` dependency.
pnpm-lock.yaml	Locks `@nestjs/config` and its transitive dependencies (dotenv, dotenv-expand, etc.).
.gitignore	Ensures local `.env` files are not committed.
.env.example	Documents the required `YOUTUBE_API_KEY` environment variable.
.devcontainer.json	Updates forwarded port to `3000` to match the app’s default HTTP port.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 11 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 11 changed files in this pull request and generated no new comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

djwmarcx

This solution requires a lot of quota. More than we have available (35x).
We need to come up with a different approach.

What about polling (for each channel):

https://www.youtube.com/feeds/videos.xml?channel_id=UCbX3YkedQunLt7EQAdVxh7w

Plus 1 call to extract the necessary data using the actual API (if really needed)

mrdarrengriffin · 2026-07-09T14:06:21Z

@djwmarcx

Switched from `search` polling to push + adaptive polling

Reworked the livestream feature to cut YouTube API quota while keeping updates near-instant.

Why: search.list costs 100 units/call — polling four channels burns the 10k/day budget fast.

Now:

WebSub push for instant "new/updated video" signals (0 quota).
videos.list (1 unit) to classify live details.
RSS discovery every 5 min (free) to catch scheduled streams push doesn't signal.
Adaptive polling: videos.list every 10s while live/imminent, ~60s otherwise, 0 when idle — catches go-live/ended in ~10s.

Reads are served from memory, so endpoints cost no quota per request.

API:

GET /livestream — all channels
GET /livestream/:slug — one channel

Returns status (live/upcoming/past/none) + title, url, startTime. Channels are config-driven (one-line to add one).

Quota: ~1,080 units for a 3h live event + ~1,150/day discovery — well under 10k.

Deploy: needs YOUTUBE_API_KEY; set PUBLIC_BASE_URL to enable push and PUBSUB_SECRET to verify payloads (see .env.example).

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

+  private reconcileTimer?: ReturnType<typeof setInterval>;
+  private discoveryTimer?: ReturnType<typeof setInterval>;
+  private tickCount = 0;
+
+  constructor(private readonly config: ConfigService) {}
+
+  async onModuleInit(): Promise<void> {
+    // Seed initial state from each channel's (free) RSS feed so we are not
+    // blank until the first push arrives.
+    await this.discovery();
+    this.discoveryTimer = setInterval(
+      () => void this.discovery(),
+      DISCOVERY_INTERVAL_MS,
+    );
+    this.reconcileTimer = setInterval(() => void this.tick(), RECONCILE_TICK_MS);
+  }


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

+    void this.subscribeAll(baseUrl);
+    this.renewTimer = setInterval(
+      () => void this.subscribeAll(baseUrl),
+      RENEW_INTERVAL_MS,
+    );


…tion

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 6 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

…nt; add pruning of expired streams. Update PubSubController to limit processed video IDs and improve signature verification. Refactor PubSubService to handle subscription errors gracefully.

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

…ubSubService to use stackOf function for improved logging of error details.

…te for channels; update PubSubController to enforce PUBSUB_SECRET validation and improve signature verification. Refactor main.ts to ensure proper raw body parsing for YouTube WebSub pushes.

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

… PUBSUB_SECRET for push notifications, improve error handling in PubSubController, and adjust raw body parsing in main.ts for HMAC verification.

Copilot

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

+    const active: string[] = [];
+    for (const videos of this.tracked.values()) {
+      for (const v of videos.values()) {
+        if (v.status === 'live' || v.status === 'upcoming') {
+          active.push(v.videoId);
+        }
+      }
+    }


+    // Seed initial state from each channel's (free) RSS feed so we are not
+    // blank until the first push arrives.
+    await this.discovery();


+  verify(@Query() query: Record<string, string>): string {
+    const challenge = query['hub.challenge'];
+    if (!challenge) {
+      throw new BadRequestException('Missing hub.challenge');
+    }
+    this.logger.log(
+      `Verified ${query['hub.mode']} for ${query['hub.topic']}`,
+    );
+    return challenge;
+  }


+    const params = new URLSearchParams({
+      'hub.mode': 'subscribe',
+      'hub.topic': topic,
+      'hub.callback': callback,
+      'hub.verify': 'async',
+      'hub.lease_seconds': String(LEASE_SECONDS),
+    });
+    if (secret) {
+      params.set('hub.secret', secret);
+    }


Add livestream service

d144070

Copilot AI review requested due to automatic review settings July 9, 2026 12:05

mrdarrengriffin marked this pull request as draft July 9, 2026 12:06

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 12:06 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/livestream/livestream.service.ts Outdated

Comment thread src/livestream/livestream.service.ts Outdated

Potential fix for pull request finding

5ff8c27

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

djwmarcx changed the title ~~Add livestream REST endpoints~~ feat: add livestream REST endpoints Jul 9, 2026

Potential fix for pull request finding

dfb64ca

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

mrdarrengriffin marked this pull request as ready for review July 9, 2026 12:13

Copilot AI review requested due to automatic review settings July 9, 2026 12:13

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 12:13 View session

mrdarrengriffin requested a review from djwmarcx July 9, 2026 12:14

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/livestream/livestream.service.ts Outdated

Comment thread src/livestream/livestream.service.ts Outdated

Comment thread src/livestream/livestream.service.ts Outdated

Potential fix for pull request finding

519a220

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 9, 2026 12:20

Potential fix for pull request finding

290fc9a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 12:20 View session

Potential fix for pull request finding

5c9b8d4

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jul 9, 2026

View reviewed changes

djwmarcx requested changes Jul 9, 2026

View reviewed changes

Switch implementation

e4bbc26

Copilot AI review requested due to automatic review settings July 9, 2026 14:06

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 14:06 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Potential fix for pull request finding

d12e059

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 9, 2026 14:14

Potential fix for pull request finding

3bee330

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 14:14 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Refactor YouTube feed URL usage to utilize a centralized feedUrl func…

9cfc4f4

…tion

Copilot AI review requested due to automatic review settings July 9, 2026 14:24

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 14:25 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Enhance LivestreamService with discovery and reconcile state manageme…

92b2eb2

…nt; add pruning of expired streams. Update PubSubController to limit processed video IDs and improve signature verification. Refactor PubSubService to handle subscription errors gracefully.

Copilot AI review requested due to automatic review settings July 9, 2026 15:00

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 15:01 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/main.ts Outdated

Comment thread src/livestream/pubsub.controller.ts Outdated

Comment thread src/livestream/livestream.service.ts

Refactor error handling in LivestreamService, PubSubController, and P…

0284ebb

…ubSubService to use stackOf function for improved logging of error details.

Copilot AI review requested due to automatic review settings July 9, 2026 15:07

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 15:08 View session

Enhance LivestreamService error handling and ensure deterministic sta…

0b463b5

…te for channels; update PubSubController to enforce PUBSUB_SECRET validation and improve signature verification. Refactor main.ts to ensure proper raw body parsing for YouTube WebSub pushes.

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/livestream/pubsub.controller.ts Outdated

Comment thread src/main.ts Outdated

Copilot AI review requested due to automatic review settings July 9, 2026 15:13

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 15:14 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/livestream/pubsub.service.ts

Comment thread .env.example Outdated

Comment thread src/livestream/pubsub.controller.ts

Comment thread src/livestream/pubsub.controller.ts Outdated

Update environment configuration and enhance PubSub handling; require…

6219cb1

… PUBSUB_SECRET for push notifications, improve error handling in PubSubController, and adjust raw body parsing in main.ts for HMAC verification.

Copilot AI review requested due to automatic review settings July 9, 2026 16:07

Copilot started reviewing on behalf of mrdarrengriffin July 9, 2026 16:08 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Uh oh!

Conversation

mrdarrengriffin commented Jul 9, 2026

Endpoints

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

djwmarcx left a comment

Choose a reason for hiding this comment

Uh oh!

mrdarrengriffin commented Jul 9, 2026

Switched from search polling to push + adaptive polling

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Switched from `search` polling to push + adaptive polling