feat: Cross-Provider Failover Pooling Support

Implemented stream pooling support for cross-provider failover scenarios. Previously, when a channel failed over to a different provider, pooling detection would fail because it searched by the failover channel's ID rather than the original requested channel ID.

### Problem

1. **Provider Profile Pooling** (issue #651 ): Streams from failover sources weren't detected during pooling checks, causing duplicate streams when using pooled provider profiles

2. **Cross-Provider Failover Pooling**: When Channel 123 (Provider A) failed over to Channel 456 (Provider B), the system couldn't pool streams because it searched for Channel 456's ID instead of the originally requested Channel 123

### Solution

Track both the requested resource (what the user asked for) and the actual source (what's currently streaming) separately:

- original_channel_id: The channel ID originally requested
- original_playlist_uuid: The playlist UUID originally requested
- id: The actual channel ID streaming (may be different due to failover)
- playlist_uuid: The actual playlist UUID (may be different due to failover)
- is_failover: Boolean flag indicating if stream is from a failover source

Author: sparkison

app/Services/M3uProxyService.php

@@ -577,6 +577,10 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
         // Get channel ID
         $id = $channel->id;
 
+        // Track the original requested channel and playlist for cross-provider failover pooling
+        $originalChannelId = $channel->id;
+        $originalPlaylistUuid = $playlist->uuid;
+
         // IMPORTANT: Check for existing pooled stream BEFORE capacity check
         // If a pooled stream exists, we can reuse it without consuming additional capacity
         // NOTE: We need to select the provider profile FIRST to check for pooled streams with the same provider
@@ -597,13 +601,14 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
                 }
             }
 
-            $existingStreamId = $this->findExistingPooledStream($id, $playlist->uuid, $profile->id, $selectedProfile?->id);
+            // Search for pooled stream by ORIGINAL channel ID (handles cross-provider failovers)
+            $existingStreamId = $this->findExistingPooledStream($originalChannelId, $originalPlaylistUuid, $profile->id, $selectedProfile?->id);
 
             if ($existingStreamId) {
                 Log::info('Reusing existing pooled transcoded stream (bypassing capacity check)', [
                     'stream_id' => $existingStreamId,
-                    'channel_id' => $id,
-                    'playlist_uuid' => $playlist->uuid,
+                    'original_channel_id' => $originalChannelId,
+                    'original_playlist_uuid' => $originalPlaylistUuid,
                     'profile_id' => $profile->id,
                     'provider_profile_id' => $selectedProfile?->id,
                 ]);
@@ -615,6 +620,7 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
         // Check if primary playlist has stream limits and if it's at capacity
         // Only check capacity if we're about to create a NEW stream (no existing pooled stream found)
         $primaryUrl = null;
+        $actualChannel = $channel;  // Track the actual channel being used (may differ from original if failover)
         if ($playlist->available_streams !== 0) {
             $activeStreams = self::getActiveStreamsCountByMetadata('playlist_uuid', $playlist->uuid);
 
@@ -660,6 +666,7 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
                         if ($failoverPlaylist->available_streams === 0) {
                             // No limits on this failover playlist, use it
                             $playlist = $failoverPlaylist;
+                            $actualChannel = $failoverChannel;  // Track that we're using a failover channel
                             $primaryUrl = PlaylistUrlService::getChannelUrl($failoverChannel, $playlist);
                             break;
                         } else {
@@ -669,6 +676,7 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
                             if ($failoverActiveStreams < $failoverPlaylist->available_streams) {
                                 // Found available failover playlist
                                 $playlist = $failoverPlaylist;
+                                $actualChannel = $failoverChannel;  // Track that we're using a failover channel
                                 $primaryUrl = PlaylistUrlService::getChannelUrl($failoverChannel, $playlist);
                                 break;
                             }
@@ -750,18 +758,32 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
             // (before capacity check) to avoid blocking reuse of existing streams.
             // If we reach here, no existing stream was found, so create a new one.
 
+            // Determine if this is a failover stream
+            $isFailover = ($actualChannel->id !== $originalChannelId);
+
             $metadata = [
-                'id' => $id,
+                'id' => $actualChannel->id,  // Actual channel being streamed
                 'type' => 'channel',
-                'playlist_uuid' => $playlist->uuid,
+                'playlist_uuid' => $playlist->uuid,  // Actual playlist being used
                 'profile_id' => $profile->id,
+                'original_channel_id' => $originalChannelId,  // For cross-provider failover pooling
+                'original_playlist_uuid' => $originalPlaylistUuid,  // For cross-provider failover pooling
+                'is_failover' => $isFailover,
             ];
 
             // Add provider profile ID if using profiles
             if ($selectedProfile) {
                 $metadata['provider_profile_id'] = $selectedProfile->id;
             }
 
+            Log::debug('Creating transcoded stream with failover tracking', [
+                'original_channel_id' => $originalChannelId,
+                'actual_channel_id' => $actualChannel->id,
+                'is_failover' => $isFailover,
+                'original_playlist_uuid' => $originalPlaylistUuid,
+                'actual_playlist_uuid' => $playlist->uuid,
+            ]);
+
             $streamId = $this->createTranscodedStream($primaryUrl, $profile, $failovers, $userAgent, $headers, $metadata);
 
             // Track connection for provider profile
@@ -773,11 +795,17 @@ public function getChannelUrl($playlist, $channel, ?Request $request = null, ?St
             return $this->buildTranscodeStreamUrl($streamId, $profile->format ?? 'ts', $username);
         } else {
             // Use direct streaming endpoint
+            // Determine if this is a failover stream
+            $isFailover = ($actualChannel->id !== $originalChannelId);
+
             $metadata = [
-                'id' => $id,
+                'id' => $actualChannel->id,  // Actual channel being streamed
                 'type' => 'channel',
-                'playlist_uuid' => $playlist->uuid,
+                'playlist_uuid' => $playlist->uuid,  // Actual playlist being used
                 'strict_live_ts' => $playlist->strict_live_ts,
+                'original_channel_id' => $originalChannelId,  // For cross-provider failover pooling
+                'original_playlist_uuid' => $originalPlaylistUuid,  // For cross-provider failover pooling
+                'is_failover' => $isFailover,
             ];
 
             // Add provider profile ID if using profiles
@@ -1472,23 +1500,27 @@ public function getPublicUrl(): string
      * This allows multiple clients to connect to the same transcoded stream without
      * consuming additional provider connections.
      *
-     * @param  int  $channelId  Channel ID
-     * @param  string  $playlistUuid  Playlist UUID
+     * Supports cross-provider failover pooling by searching based on the ORIGINAL
+     * requested channel, not the actual source channel (which may be a failover).
+     *
+     * @param  int  $channelId  Original requested channel ID
+     * @param  string  $playlistUuid  Original requested playlist UUID
      * @param  int|null  $profileId  StreamProfile ID (transcoding profile)
      * @param  int|null  $providerProfileId  PlaylistProfile ID (provider profile)
      * @return string|null Stream ID if found, null otherwise
      */
     protected function findExistingPooledStream(int $channelId, string $playlistUuid, ?int $profileId = null, ?int $providerProfileId = null): ?string
     {
         try {
-            // Query m3u-proxy for streams by metadata
+            // Query m3u-proxy for streams by ORIGINAL channel ID metadata
+            // This enables pooling across different provider failovers
             $endpoint = $this->apiBaseUrl.'/streams/by-metadata';
             $response = Http::timeout(5)->acceptJson()
                 ->withHeaders(array_filter([
                     'X-API-Token' => $this->apiToken,
                 ]))
                 ->get($endpoint, [
-                    'field' => 'id',
+                    'field' => 'original_channel_id',  // Search by original, not actual channel
                     'value' => (string) $channelId,
                     'active_only' => true,  // Only return active streams
                 ]);
@@ -1505,22 +1537,25 @@ protected function findExistingPooledStream(int $channelId, string $playlistUuid
                 $metadata = $stream['metadata'] ?? [];
 
                 // Check if this stream matches our criteria:
-                // 1. Same channel ID
-                // 2. Same playlist UUID
+                // 1. Same ORIGINAL channel ID (enables cross-provider failover pooling)
+                // 2. Same ORIGINAL playlist UUID (enables cross-provider failover pooling)
                 // 3. Is a transcoded stream (has transcoding metadata)
                 // 4. Same StreamProfile ID (transcoding profile, if specified)
                 // 5. Same PlaylistProfile ID (provider profile, if specified)
                 if (
-                    ($metadata['id'] ?? null) == $channelId &&
-                    ($metadata['playlist_uuid'] ?? null) === $playlistUuid &&
+                    ($metadata['original_channel_id'] ?? null) == $channelId &&
+                    ($metadata['original_playlist_uuid'] ?? null) === $playlistUuid &&
                     ($metadata['transcoding'] ?? null) === 'true' &&
                     ($profileId === null || ($metadata['profile_id'] ?? null) == $profileId) &&
                     ($providerProfileId === null || ($metadata['provider_profile_id'] ?? null) == $providerProfileId)
                 ) {
-                    Log::info('Found existing pooled transcoded stream', [
+                    Log::info('Found existing pooled transcoded stream (cross-provider failover support)', [
                         'stream_id' => $stream['stream_id'],
-                        'channel_id' => $channelId,
-                        'playlist_uuid' => $playlistUuid,
+                        'original_channel_id' => $channelId,
+                        'original_playlist_uuid' => $playlistUuid,
+                        'actual_channel_id' => $metadata['id'] ?? null,
+                        'actual_playlist_uuid' => $metadata['playlist_uuid'] ?? null,
+                        'is_failover' => $metadata['is_failover'] ?? false,
                         'profile_id' => $profileId,
                         'provider_profile_id' => $providerProfileId,
                         'client_count' => $stream['client_count'],

docs/stream-pooling.md

@@ -100,14 +100,19 @@ The m3u-proxy handles the actual stream pooling:
 1. **Stream Creation**: Each transcoded stream includes metadata:
    ```json
    {
-     "id": "12345",
+     "id": "456",
      "type": "channel",
-     "playlist_uuid": "abc-def-123",
+     "playlist_uuid": "provider-b-uuid",
      "transcoding": "true",
      "profile_id": "5",
-     "provider_profile_id": "2"
+     "provider_profile_id": "2",
+     "original_channel_id": "123",
+     "original_playlist_uuid": "provider-a-uuid",
+     "is_failover": true
    }
    ```
+   
+   Note: `id` and `playlist_uuid` represent the ACTUAL source, while `original_*` fields track the REQUESTED channel for cross-provider pooling.
 
 2. **Client Registration**: Multiple clients can register to the same stream
 3. **FFmpeg Process Sharing**: All clients receive data from the same FFmpeg transcoding process
@@ -163,12 +168,14 @@ Provider limits are respected automatically:
 ### For Pooling to Work
 
 1. **Transcoding must be enabled** (profile parameter provided)
-2. **Same channel** (same channel ID)
-3. **Same playlist** (same playlist UUID)
+2. **Same original channel** (same original channel ID - even if served from different failover sources)
+3. **Same original playlist** (same original playlist UUID - even if served from different failover playlists)
 4. **Same transcoding profile** (StreamProfile ID)
 5. **Same provider profile** (PlaylistProfile ID, if using pooled provider profiles)
 6. **Stream still active** (has at least one connected client)
 
+**New in v1.x**: Pooling now works across cross-provider failovers! If Channel 123 from Provider A fails over to Channel 456 from Provider B, subsequent requests for Channel 123 will correctly pool into the existing stream.
+
 ### Direct Streams (Non-Transcoded)
 
 Direct streams (without transcoding) **do NOT pool** because:
@@ -220,20 +227,30 @@ Look for these log messages:
 
 ### m3u-editor Logs
 ```
-[INFO] Found existing pooled transcoded stream
+[INFO] Found existing pooled transcoded stream (cross-provider failover support)
   stream_id: abc123...
-  channel_id: 12345
-  playlist_uuid: xyz789...
+  original_channel_id: 123
+  original_playlist_uuid: provider-a-uuid
+  actual_channel_id: 456
+  actual_playlist_uuid: provider-b-uuid
+  is_failover: true
   profile_id: 5
   provider_profile_id: 2
   client_count: 3
 
 [INFO] Reusing existing pooled transcoded stream (bypassing capacity check)
   stream_id: abc123...
-  channel_id: 12345
-  playlist_uuid: xyz789...
+  original_channel_id: 123
+  original_playlist_uuid: provider-a-uuid
   profile_id: 5
   provider_profile_id: 2
+
+[DEBUG] Creating transcoded stream with failover tracking
+  original_channel_id: 123
+  actual_channel_id: 456
+  is_failover: true
+  original_playlist_uuid: provider-a-uuid
+  actual_playlist_uuid: provider-b-uuid
 ```
 
 ### m3u-proxy Logs
@@ -272,11 +289,11 @@ curl -H "X-API-Token: your-token" \
 ```
 
 **Common Issues**:
-- Different playlists (playlist_uuid doesn't match)
+- Different original channels (original_channel_id doesn't match)
+- Different original playlists (original_playlist_uuid doesn't match)
 - Different transcoding profiles (profile_id doesn't match)
 - Different provider profiles (provider_profile_id doesn't match)
 - Stream expired (no active clients when new user tries to connect)
-- Failover sources not matching (fixed in v1.x - now properly matches provider_profile_id)
 
 ### Stream Quality Issues