fix: preserve SABR playback across gateway outages

Author: Priveetee

src/http-client.ts

@@ -8,6 +8,10 @@ class TypeTypeHttpError extends Error {
   }
 }
 
+const MAX_TRANSIENT_RETRIES = 24;
+const MAX_RETRY_DELAY_MS = 3_000;
+const TRANSIENT_STATUSES = new Set([502, 503, 504]);
+
 export type HttpClientOptions = {
   endpoint: string;
   headers?: HeadersInit;
@@ -32,7 +36,7 @@ export class HttpClient {
   }
 
   response(url: string, init?: RequestInit): Promise<Response> {
-    return this.fetchRaw(url, init);
+    return this.fetchWithTransientRetry(url, init);
   }
 
   absolute(path: string): string {
@@ -44,11 +48,26 @@ export class HttpClient {
   }
 
   private async fetchAbsolute(url: string, init?: RequestInit): Promise<Response> {
-    const response = await this.fetchRaw(url, init);
+    const response = await this.fetchWithTransientRetry(url, init);
     if (!response.ok) throw new TypeTypeHttpError(response.statusText, response.status);
     return response;
   }
 
+  private async fetchWithTransientRetry(url: string, init?: RequestInit): Promise<Response> {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        const response = await this.fetchRaw(url, init);
+        if (!TRANSIENT_STATUSES.has(response.status) || attempt >= MAX_TRANSIENT_RETRIES)
+          return response;
+        await retryDelay(response, attempt, init?.signal);
+      } catch (error) {
+        if (isAbortError(error)) throw error;
+        if (attempt >= MAX_TRANSIENT_RETRIES) throw error;
+        await retryDelay(null, attempt, init?.signal);
+      }
+    }
+  }
+
   private async fetchRaw(url: string, init?: RequestInit): Promise<Response> {
     const headers = new Headers(this.options.headers);
     new Headers(init?.headers).forEach((value, key) => {
@@ -63,3 +82,41 @@ export class HttpClient {
       : `${this.options.endpoint}/`;
   }
 }
+
+function retryDelay(
+  response: Response | null,
+  attempt: number,
+  signal?: AbortSignal | null,
+): Promise<void> {
+  const headerDelay = response ? retryAfterMs(response.headers.get("retry-after")) : null;
+  const delayMs = headerDelay ?? Math.min(MAX_RETRY_DELAY_MS, 500 * 2 ** attempt);
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Operation aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(finish, delayMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    function finish(): void {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }
+    function abort(): void {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new DOMException("Operation aborted", "AbortError"));
+    }
+  });
+}
+
+function retryAfterMs(value: string | null): number | null {
+  if (value === null) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(MAX_RETRY_DELAY_MS, seconds * 1000);
+  const dateMs = Date.parse(value);
+  if (!Number.isFinite(dateMs)) return null;
+  return Math.min(MAX_RETRY_DELAY_MS, Math.max(0, dateMs - Date.now()));
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}

src/player-state.ts

@@ -12,10 +12,10 @@ export class PlayerState {
     this.emitter.emit({ type: "state", state });
   }
 
-  fail(error: Error): void {
+  fail(error: Error, recoveryPositionMs: number): void {
     if (error.name === "AbortError") return;
     this.set("error");
-    this.emitter.emit({ type: "error", error });
+    this.emitter.emit({ type: "error", error, recoveryPositionMs });
   }
 
   destroy(): void {

src/type-type-mse-player.ts

@@ -32,6 +32,7 @@ import type {
   private loadTask: Promise<void> | null = null;
   private sessionTransition: Promise<void> = Promise.resolve();
   private audioOnly: boolean;
+  private recoveryPositionMs: number;
   private destroyed = false;
 
   /** Creates a player without starting network or media operations. */ constructor(
@@ -41,6 +42,7 @@ import type {
     this.video.crossOrigin = "anonymous";
     this.video.playsInline = true;
     this.audioOnly = config.audioOnly === true;
+    this.recoveryPositionMs = Math.max(0, Math.round(config.startTimeMs ?? 0));
     this.deps = createPlayerDeps({
       video,
       config,
@@ -49,7 +51,10 @@ import type {
       signal: () => this.operation.signal,
       state: (state) => this.playerState.set(state),
       error: (error) => this.reportPlaybackFailure(error),
-      progress: (positionMs) => this.playbackRecovery.observeProgress(positionMs),
+      progress: (positionMs) => {
+        this.rememberRecoveryPosition(positionMs);
+        this.playbackRecovery.observeProgress(positionMs);
+      },
       loopError: (error, context) => this.handlePlaybackLoopError(error, context),
     });
     this.deps.mediaEvents.start();
@@ -63,7 +68,10 @@ import type {
 
   /** Creates the initial playback session and fills the first media window. */ load(): Promise<void> {
     ensurePlayerAlive(this.destroyed);
-    const task = this.loadInitialSession();
+    const task = this.loadInitialSession().catch((error: unknown) => {
+      if (!isAbortError(error)) this.reportPlaybackFailure(asError(error));
+      throw error;
+    });
     this.loadTask = task;
     const clearTask = () => {
       if (this.loadTask === task) this.loadTask = null;
@@ -79,6 +87,7 @@ import type {
     const signal = this.operation.signal;
     this.playerState.set("loading");
     const startTimeMs = Math.max(0, Math.round(this.config.startTimeMs ?? 0));
+    this.recoveryPositionMs = startTimeMs;
     const response = await this.deps.playback.create(
       {
         videoId: this.config.videoId,
@@ -116,6 +125,7 @@ import type {
   async seek(positionMs: number): Promise<void> {
     this.playbackIntent.capture(this.video.paused, this.playerState.value === "seeking");
     const targetMs = Math.max(0, Math.round(positionMs));
+    this.recoveryPositionMs = targetMs;
     return this.seekController.seek(
       targetMs,
       `seek:${targetMs}`,
@@ -323,7 +333,8 @@ import type {
       this.reportPlaybackFailure(error);
       return;
     }
-    const positionMs = currentTimeMs(this.video);
+    this.rememberRecoveryPosition(currentTimeMs(this.video));
+    const positionMs = this.recoveryPositionMs;
     const decision = this.playbackRecovery.begin(sessionId);
     if (decision === "ignore") return;
     if (decision === "exhausted") {
@@ -380,13 +391,21 @@ import type {
   /** Publishes one final playback failure and aborts pending media work. */
   private reportPlaybackFailure(error: Error): void {
     if (this.destroyed) return;
+    this.rememberRecoveryPosition(currentTimeMs(this.video));
     this.playbackRecovery.reportOnce(error, (failure) => {
       this.operation.abort();
       this.deps.loop.stop();
-      this.playerState.fail(failure);
+      this.playerState.fail(failure, this.recoveryPositionMs);
     });
   }
 
+  /** Keeps the last usable media position across source teardown. */
+  private rememberRecoveryPosition(positionMs: number): void {
+    if (Number.isFinite(positionMs) && positionMs > 0) {
+      this.recoveryPositionMs = Math.round(positionMs);
+    }
+  }
+
   /** Serializes MediaSource ownership transitions. */
   private enqueueSessionTransition<T>(work: () => Promise<T>): Promise<T> {
     const result = this.sessionTransition.then(work, work);

src/types.ts

@@ -46,7 +46,7 @@ export type TypeTypeMseEvent =
   | { type: "segment"; kind: TrackKind; url: string; startMs: number; durationMs: number }
   | { type: "buffer"; bufferedEndMs: number; currentTimeMs: number }
   | { type: "seek"; positionMs: number }
-  | { type: "error"; error: Error };
+  | { type: "error"; error: Error; recoveryPositionMs: number };
 
 /** Discriminant accepted by {@link TypeTypeMsePlayer.on}. */
 export type TypeTypeMseEventType = TypeTypeMseEvent["type"];

tests/http-client.test.ts

@@ -1,9 +1,80 @@
-import { expect, test } from "bun:test";
+import { afterEach, expect, test } from "bun:test";
 import { HttpClient } from "../src/http-client";
 
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
 test("preserves endpoint path for absolute API URLs", () => {
   const http = new HttpClient({ endpoint: "https://beta.typetype.video/api" });
   expect(http.absolute("/sabr/playback/session/manifest")).toBe(
     "https://beta.typetype.video/api/sabr/playback/session/manifest",
   );
 });
+
+test("retries transient gateway responses", async () => {
+  let requests = 0;
+  globalThis.fetch = () => {
+    requests += 1;
+    if (requests < 3) {
+      return Promise.resolve(new Response(null, { status: 502, headers: { "retry-after": "0" } }));
+    }
+    return Promise.resolve(Response.json({ ready: true }));
+  };
+
+  const result = await new HttpClient({ endpoint: "https://example.test/api" }).json("/window");
+
+  expect(result).toEqual({ ready: true });
+  expect(requests).toBe(3);
+});
+
+test("does not retry permanent client errors", async () => {
+  let requests = 0;
+  globalThis.fetch = () => {
+    requests += 1;
+    return Promise.resolve(new Response(null, { status: 400, statusText: "Bad Request" }));
+  };
+
+  await expect(
+    new HttpClient({ endpoint: "https://example.test/api" }).json("/window"),
+  ).rejects.toMatchObject({ status: 400 });
+  expect(requests).toBe(1);
+});
+
+test("returns permanent segment errors to the caller", async () => {
+  globalThis.fetch = () => Promise.resolve(new Response(null, { status: 404 }));
+
+  const response = await new HttpClient({ endpoint: "https://example.test/api" }).response(
+    "https://example.test/segment",
+  );
+
+  expect(response.status).toBe(404);
+});
+
+test("bounds transient gateway retries", async () => {
+  let requests = 0;
+  globalThis.fetch = () => {
+    requests += 1;
+    return Promise.resolve(new Response(null, { status: 503, headers: { "retry-after": "0" } }));
+  };
+
+  await expect(
+    new HttpClient({ endpoint: "https://example.test/api" }).json("/window"),
+  ).rejects.toMatchObject({ status: 503 });
+  expect(requests).toBe(25);
+});
+
+test("aborts a pending transient retry", async () => {
+  const controller = new AbortController();
+  globalThis.fetch = () =>
+    Promise.resolve(new Response(null, { status: 503, headers: { "retry-after": "3" } }));
+  const request = new HttpClient({ endpoint: "https://example.test/api" }).json("/window", {
+    signal: controller.signal,
+  });
+
+  controller.abort();
+
+  await expect(request).rejects.toMatchObject({ name: "AbortError" });
+});

tests/type-type-mse-recovery.test.ts

@@ -22,11 +22,13 @@ type RecoveryHarness = {
   operation: PlayerOperation;
   playbackRecovery: PlaybackRecovery;
   playbackIntent: PlaybackIntent;
+  recoveryPositionMs: number;
+  loadTask: Promise<void> | null;
   emitter: { emit: (event: { type: string; videoItag?: number }) => void };
   playerState: {
     value: TypeTypeMseState;
     set: (state: TypeTypeMseState) => void;
-    fail: (error: Error) => void;
+    fail: (error: Error, recoveryPositionMs: number) => void;
   };
   deps: {
     loop: { stop: () => void };
@@ -39,6 +41,8 @@ type RecoveryHarness = {
   switchSession: (...args: unknown[]) => Promise<LoadedSession>;
   handlePlaybackLoopError: (error: Error, context: PlaybackLoopFailureContext) => void;
   reportPlaybackFailure: (error: Error) => void;
+  loadInitialSession: () => Promise<void>;
+  load: () => Promise<void>;
   enqueueSessionTransition: <T>(work: () => Promise<T>) => Promise<T>;
   sessionTransition: Promise<void>;
 };
@@ -74,13 +78,16 @@ function harness(
   player: RecoveryHarness;
   requests: CreatePlaybackRequest[];
   failures: Error[];
+  failurePositions: number[];
   qualities: number[];
 } {
   const player = Object.create(TypeTypeMsePlayer.prototype) as RecoveryHarness;
   const requests: CreatePlaybackRequest[] = [];
   const failures: Error[] = [];
+  const failurePositions: number[] = [];
   const qualities: number[] = [];
   player.destroyed = false;
+  player.loadTask = null;
   player.sessionTransition = Promise.resolve();
   player.session = loaded("source");
   player.operation = new PlayerOperation();
@@ -89,7 +96,10 @@ function harness(
   player.playerState = {
     value: "playing",
     set: (state) => (player.playerState.value = state),
-    fail: (error) => failures.push(error),
+    fail: (error, positionMs) => {
+      failures.push(error);
+      failurePositions.push(positionMs);
+    },
   };
   player.deps = {
     loop: { stop: () => undefined },
@@ -108,6 +118,7 @@ function harness(
     },
   };
   player.video = { paused, currentTime: 379.441 };
+  player.recoveryPositionMs = 379_441;
   player.config = {
     endpoint: "https://beta.typetype.video/api",
     videoId: "nt1TGErpc0Q",
@@ -122,7 +133,7 @@ function harness(
     player.session = next;
     return next;
   };
-  return { player, requests, failures, qualities };
+  return { player, requests, failures, failurePositions, qualities };
 }
 
 function response(sessionId: string): PlaybackResponse {
@@ -249,7 +260,7 @@ test("serializes media source session transitions", async () => {
 });
 
 test("a generic failure aborts pending recovery and is reported once", async () => {
-  const { player, failures } = harness(
+  const { player, failures, failurePositions } = harness(
     async (_request, signal) =>
       new Promise<PlaybackResponse>((_resolve, reject) => {
         signal?.addEventListener(
@@ -264,6 +275,7 @@ test("a generic failure aborts pending recovery and is reported once", async ()
     signal: player.operation.signal,
   });
   const generic = new Error("media append failed");
+  player.video.currentTime = 0;
 
   player.handlePlaybackLoopError(generic, {
     sessionId: "source",
@@ -273,9 +285,22 @@ test("a generic failure aborts pending recovery and is reported once", async ()
   await Bun.sleep(0);
 
   expect(failures).toEqual([generic]);
+  expect(failurePositions).toEqual([379_441]);
   expect(player.operation.signal.aborted).toBe(true);
 });
 
+test("an initial load failure reports its configured recovery position", async () => {
+  const { player, failures, failurePositions } = harness(async () => response("unused"));
+  const failure = new Error("gateway unavailable");
+  player.video.currentTime = 0;
+  player.loadInitialSession = () => Promise.reject(failure);
+
+  await expect(player.load()).rejects.toBe(failure);
+
+  expect(failures).toEqual([failure]);
+  expect(failurePositions).toEqual([379_441]);
+});
+
 test("an old generic failure cannot replace an active recovery", async () => {
   let release: ((value: PlaybackResponse) => void) | null = null;
   const pending = new Promise<PlaybackResponse>((resolve) => {