feat(superflix): implement next episode prefetching and enhance stream caching mechanisms

Author: alvarorichard

internal/api/enhanced.go

@@ -659,8 +659,86 @@ var (
 	// sfReleaseBrowserFn closes the solver window after a resolve. A seam so tests
 	// can assert it fires on every path (cache hit, server list, sniff, error).
 	sfReleaseBrowserFn = superflix.ReleaseSharedBrowser
+
+	// sfPrefetchNextFn warms the next episode's stream cache after a successful
+	// resolve. A seam so tests can stub it out or drive it directly.
+	sfPrefetchNextFn = maybePrefetchNextSuperFlixEpisode
 )
 
+// sfPrefetchBudget bounds the background next-episode warm-up. The chain is
+// plain HTTP (browser solve forbidden), but the player-page fetch retries past
+// token-less shells and the transport may honor a Retry-After, so give it room;
+// nothing user-visible waits on this.
+const sfPrefetchBudget = 45 * time.Second
+
+var (
+	// sfPrefetchInFlight dedupes concurrent warm-ups of the same episode.
+	sfPrefetchInFlight sync.Map
+	// sfPrefetchWG tracks warm-up goroutines so tests can wait for them.
+	sfPrefetchWG sync.WaitGroup
+)
+
+// maybePrefetchNextSuperFlixEpisode warms the NEXT episode's (host, hash) cache
+// entry in the background, so a binge's "next episode" opens through the ~1s
+// cache fast path instead of paying the server-list wait again.
+//
+// Strictly best-effort and invisible: the whole chain runs with the browser
+// solve FORBIDDEN (WithoutBrowserSolve), so it can never pop a window — with the
+// Cloudflare clearance warm from the play that just happened, the tokened player
+// page is reachable over plain HTTP. Any failure (gate re-armed, no next
+// episode, rate limit) only means the next play resolves normally. The server is
+// picked silently from the user's remembered preference and the pick is NOT
+// re-persisted, so prefetch never influences a later prompt.
+//
+// GOANIME_SF_NO_PREFETCH disables it (escape hatch for metered connections or
+// if SuperFlix ever turns hostile to the extra requests).
+func maybePrefetchNextSuperFlixEpisode(sfClient *superflix.SuperFlixClient, tmdbID, sfType, season, epNum string) {
+	if sfType != "serie" || os.Getenv("GOANIME_SF_NO_PREFETCH") != "" {
+		return
+	}
+	n, err := strconv.Atoi(strings.TrimSpace(epNum))
+	if err != nil || n < 1 {
+		return
+	}
+	next := strconv.Itoa(n + 1)
+	if superflix.HasCachedStream(sfType, tmdbID, season, next) {
+		return
+	}
+	key := sfType + ":" + tmdbID + ":" + season + ":" + next
+	if _, running := sfPrefetchInFlight.LoadOrStore(key, struct{}{}); running {
+		return
+	}
+	// Capture the seams synchronously: the goroutine may outlive a test that
+	// restores them, and reading the package vars there would be a data race.
+	getServers, streamFromServer := sfGetServersFn, sfStreamFromServerFn
+	sfPrefetchWG.Add(1)
+	go func() {
+		defer sfPrefetchWG.Done()
+		defer sfPrefetchInFlight.Delete(key)
+
+		ctx, cancel := context.WithTimeout(superflix.WithoutBrowserSolve(context.Background()), sfPrefetchBudget)
+		defer cancel()
+
+		servers, tokens, err := getServers(sfClient, ctx, sfType, tmdbID, season, next)
+		if err != nil || len(servers) == 0 {
+			util.Debug("SuperFlix prefetch: server list unavailable; next episode will resolve normally", "key", key, "err", err)
+			return
+		}
+		candidates := orderedServers(servers)
+		if pref, ok := recallSuperFlixServer(tmdbID); ok {
+			candidates = narrowByMemory(candidates, pref)
+		}
+		// StreamFromServer caches the (host, hash) — the browser-gated fact —
+		// as a side effect; the stream URL itself is discarded (signed links
+		// expire, and the cache replay signs a fresh one at play time).
+		if _, err := streamFromServer(sfClient, ctx, tokens, candidates[0].IDString(), sfType, tmdbID, season, next); err != nil {
+			util.Debug("SuperFlix prefetch failed; next episode will resolve normally", "key", key, "err", err)
+			return
+		}
+		util.Debug("SuperFlix prefetch: next episode cached for instant start", "key", key)
+	}()
+}
+
 // superFlixStream resolves a SuperFlix stream, preferring the path that lets the
 // user actually choose.
 //
@@ -786,6 +864,10 @@ func GetSuperFlixStreamURL(media *models.Anime, episode *models.Episode, quality
 		return "", fmt.Errorf("failed to get SuperFlix stream: %w", describeSuperFlixErr(err))
 	}
 
+	// Warm the NEXT episode in the background (best-effort, plain HTTP, no
+	// browser window) so a binge's next play starts from the cache fast path.
+	sfPrefetchNextFn(sfClient, tmdbID, sfType, season, epNum)
+
 	// Store referer globally for mpv playback
 	if result.Referer != "" {
 		util.SetGlobalReferer(result.Referer)

internal/api/superflix_prefetch_test.go

@@ -0,0 +1,141 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"sync"
+	"testing"
+
+	"github.com/alvarorichard/Goanime/internal/scraper/providers/superflix"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// stubPrefetchSeams replaces the server-list and stream seams with counters and
+// returns them, restoring the originals on cleanup. The stubs are safe to call
+// from the prefetch goroutine after the test ends (they touch only their own
+// captured state, never testing.T).
+type prefetchSeamCalls struct {
+	mu               sync.Mutex
+	getServersEp     []string
+	streamFromServer []string // "serverID episode" per call
+}
+
+func stubPrefetchSeams(t *testing.T, servers []superflix.SuperFlixServer) *prefetchSeamCalls {
+	t.Helper()
+	calls := &prefetchSeamCalls{}
+	pl, ps := sfGetServersFn, sfStreamFromServerFn
+	t.Cleanup(func() { sfGetServersFn, sfStreamFromServerFn = pl, ps })
+
+	sfGetServersFn = func(_ *superflix.SuperFlixClient, _ context.Context, _, _, _, episode string) ([]superflix.SuperFlixServer, *superflix.SuperFlixTokens, error) {
+		calls.mu.Lock()
+		calls.getServersEp = append(calls.getServersEp, episode)
+		calls.mu.Unlock()
+		return servers, &superflix.SuperFlixTokens{ContentID: "1", PageToken: "tok"}, nil
+	}
+	sfStreamFromServerFn = func(_ *superflix.SuperFlixClient, _ context.Context, _ *superflix.SuperFlixTokens, serverID, _, _, _, episode string) (*superflix.SuperFlixStreamResult, error) {
+		calls.mu.Lock()
+		calls.streamFromServer = append(calls.streamFromServer, serverID+" "+episode)
+		calls.mu.Unlock()
+		return &superflix.SuperFlixStreamResult{StreamURL: "https://cdn/x.m3u8"}, nil
+	}
+	return calls
+}
+
+func sfTestServer(id string, audioType int, isFile bool) superflix.SuperFlixServer {
+	return superflix.SuperFlixServer{
+		ID:     json.RawMessage(`"` + id + `"`),
+		Name:   "Servidor " + id,
+		Type:   audioType,
+		IsFile: isFile,
+	}
+}
+
+// The warm-up must target episode N+1 and honor the remembered server
+// preference silently — no picker, no persisted pick.
+func TestMaybePrefetchNextSuperFlixEpisode_WarmsNextEpisode(t *testing.T) {
+	dub := sfTestServer("111", superflix.SuperFlixAudioDubbed, false)
+	leg := sfTestServer("222", superflix.SuperFlixAudioSubtitled, false)
+	calls := stubPrefetchSeams(t, []superflix.SuperFlixServer{dub, leg})
+
+	const tmdbID = "goanime-prefetch-test-424242"
+	t.Cleanup(resetSuperFlixServerPrefs)
+	resetSuperFlixServerPrefs()
+	// The user picked Legendado on the episode that just played.
+	rememberSuperFlixServer(tmdbID, leg)
+
+	maybePrefetchNextSuperFlixEpisode(nil, tmdbID, "serie", "1", "3")
+	sfPrefetchWG.Wait()
+
+	calls.mu.Lock()
+	defer calls.mu.Unlock()
+	require.Equal(t, []string{"4"}, calls.getServersEp, "must warm exactly the NEXT episode")
+	require.Equal(t, []string{"222 4"}, calls.streamFromServer,
+		"must resolve through the remembered (legendado) server, silently")
+}
+
+// Guards: anything that is not a numbered series episode must not spawn a
+// warm-up at all, and the kill-switch must be honored.
+func TestMaybePrefetchNextSuperFlixEpisode_Guards(t *testing.T) {
+	tests := []struct {
+		name   string
+		sfType string
+		epNum  string
+		env    string
+	}{
+		{"movie is skipped", "filme", "1", ""},
+		{"non-numeric episode is skipped", "serie", "especial", ""},
+		{"episode zero is skipped", "serie", "0", ""},
+		{"kill-switch is honored", "serie", "3", "1"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			calls := stubPrefetchSeams(t, []superflix.SuperFlixServer{
+				sfTestServer("111", superflix.SuperFlixAudioDubbed, false),
+			})
+			if tt.env != "" {
+				t.Setenv("GOANIME_SF_NO_PREFETCH", tt.env)
+			}
+
+			maybePrefetchNextSuperFlixEpisode(nil, "goanime-prefetch-guard-test", tt.sfType, "1", tt.epNum)
+			sfPrefetchWG.Wait()
+
+			calls.mu.Lock()
+			defer calls.mu.Unlock()
+			assert.Empty(t, calls.getServersEp, "no warm-up may run for this input")
+		})
+	}
+}
+
+// A failing server list must die silently in the background — no panic, no
+// stream call — and release the in-flight slot so a later attempt can run.
+func TestMaybePrefetchNextSuperFlixEpisode_FailureIsSilentAndReleasesSlot(t *testing.T) {
+	pl, ps := sfGetServersFn, sfStreamFromServerFn
+	t.Cleanup(func() { sfGetServersFn, sfStreamFromServerFn = pl, ps })
+
+	var mu sync.Mutex
+	var attempts int
+	sfGetServersFn = func(_ *superflix.SuperFlixClient, _ context.Context, _, _, _, _ string) ([]superflix.SuperFlixServer, *superflix.SuperFlixTokens, error) {
+		mu.Lock()
+		attempts++
+		mu.Unlock()
+		return nil, nil, superflix.ErrSuperFlixRateLimited
+	}
+	streamCalled := false
+	sfStreamFromServerFn = func(_ *superflix.SuperFlixClient, _ context.Context, _ *superflix.SuperFlixTokens, _, _, _, _, _ string) (*superflix.SuperFlixStreamResult, error) {
+		streamCalled = true
+		return nil, nil
+	}
+
+	const tmdbID = "goanime-prefetch-fail-test"
+	maybePrefetchNextSuperFlixEpisode(nil, tmdbID, "serie", "1", "7")
+	sfPrefetchWG.Wait()
+	// The in-flight slot must be free again: a second attempt runs.
+	maybePrefetchNextSuperFlixEpisode(nil, tmdbID, "serie", "1", "7")
+	sfPrefetchWG.Wait()
+
+	mu.Lock()
+	defer mu.Unlock()
+	assert.Equal(t, 2, attempts, "failed warm-up must release the in-flight slot")
+	assert.False(t, streamCalled, "no stream resolve after a failed server list")
+}

internal/scraper/providers/superflix/perf_bench_test.go

@@ -0,0 +1,83 @@
+package superflix
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/PuerkitoBio/goquery"
+)
+
+// benchSearchHTML builds a search results page with n media cards in the
+// current SuperFlix markup (group/card, data-msg buttons, mt-3 span metadata).
+func benchSearchHTML(n int) string {
+	var b strings.Builder
+	b.WriteString(`<html><body><div id="results">`)
+	for i := 0; i < n; i++ {
+		fmt.Fprintf(&b, `
+<div class="group/card">
+  <img alt="Título de Teste %d" src="https://d1muf25xaso8hp.cloudfront.net/https://image.tmdb.org/t/p/w342/poster%d.jpg">
+  <h3>Título de Teste %d</h3>
+  <button data-msg="Copiar TMDB" data-copy="%d"></button>
+  <button data-msg="Copiar IMDB" data-copy="tt%07d"></button>
+  <button data-msg="Copiar Link" data-copy="https://superflixapi.pro/serie/%d"></button>
+  <div class="mt-3"><span>2021</span><span>Série</span></div>
+</div>`, i, i, i, 100000+i, i, 100000+i)
+	}
+	b.WriteString(`</div></body></html>`)
+	return b.String()
+}
+
+func BenchmarkParseCards(b *testing.B) {
+	html := benchSearchHTML(48) // a full search results page
+	c := &SuperFlixClient{}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		doc, err := goquery.NewDocumentFromReader(strings.NewReader(html))
+		if err != nil {
+			b.Fatal(err)
+		}
+		if got := c.parseCards(doc); len(got) != 48 {
+			b.Fatalf("expected 48 cards, got %d", len(got))
+		}
+	}
+}
+
+// benchEpisodesHTML builds a serie page carrying a window.allEpisodes blob with
+// the given seasons × episodes.
+func benchEpisodesHTML(seasons, episodes int) string {
+	var b strings.Builder
+	b.WriteString(`<html><head><script>window.allEpisodes = {`)
+	for s := 1; s <= seasons; s++ {
+		if s > 1 {
+			b.WriteString(",")
+		}
+		fmt.Fprintf(&b, `"%d":[`, s)
+		for e := 1; e <= episodes; e++ {
+			if e > 1 {
+				b.WriteString(",")
+			}
+			fmt.Fprintf(&b, `{"epi_num":%d,"title":"Episódio %d","air_date":"2021-04-%02d"}`, e, e, (e%28)+1)
+		}
+		b.WriteString("]")
+	}
+	b.WriteString(`};</script></head><body></body></html>`)
+	return b.String()
+}
+
+func BenchmarkExtractEpisodes(b *testing.B) {
+	html := benchEpisodesHTML(10, 24) // long-running dorama/anime scale
+	c := &SuperFlixClient{}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		out, err := c.ExtractEpisodes(html)
+		if err != nil {
+			b.Fatal(err)
+		}
+		if len(out) != 10 {
+			b.Fatalf("expected 10 seasons, got %d", len(out))
+		}
+	}
+}

internal/scraper/providers/superflix/servers_nosolve_test.go

@@ -76,7 +76,9 @@ func TestGetServers_AllowsBrowserSolve(t *testing.T) {
 // gate if it has to. Locking the enhancement's no-solve rule must not accidentally
 // gag the stream path.
 func TestStreamFromServer_DoesNotForbidBrowserSolve(t *testing.T) {
-	t.Parallel()
+	// Not parallel: swaps the global stream cache. Without the swap this test
+	// wrote its httptest (host, hash) into the USER'S real on-disk cache.
+	withFreshStreamCache(t)
 
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch {