refactor(player): the Plex session machine is a tested engine, one request per item in flight
PlexPlayer's session logic (generation, pending play intent, clock ownership, session offset, reclaim
budget, listener teardown) moves into lib/hlsEngine.ts, a plain class with hls.js behind lib/hlsPort.ts
and its own unit tests.
- A seek, track change or reclaim asked for while a session request is out replaces the queued
target; it is sent once the in-flight answer settles. A burst of 20 presses past the buffer was 20
requests and 20 ffmpeg spawns; it is now 2-3, and plays again ~2 s sooner.
- The player stops its server session when it leaves the item, closes or the page unloads
(POST /api/plex/stream/{rk}/session/{sid}/stop, identity-aware). A left transcode used to run to
the end of the film first.
- A restart asked for after a new session attached but before it played no longer reads the emptied
media as the viewer's pause.
This commit is contained in:
@@ -0,0 +1,517 @@
|
||||
// The Plex player's session machine, without React, hls.js or a media pipeline: every race it exists
|
||||
// to win, driven step by step. PlexPlayer's DOM tests hold the same behaviour through the component.
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import type { PlexPlaySession } from "./api";
|
||||
import {
|
||||
HlsEngine,
|
||||
MAX_SESSION_RECLAIMS,
|
||||
RECLAIM_WINDOW_MS,
|
||||
type EngineDeps,
|
||||
type HlsHandlers,
|
||||
type HlsPort,
|
||||
type SessionParams,
|
||||
} from "./hlsEngine";
|
||||
import { HLS_SUB_LAG } from "./plexPlayerPrefs";
|
||||
|
||||
/** A <video> stand-in: the media calls the engine makes, and events the test fires. */
|
||||
class FakeMedia extends EventTarget {
|
||||
paused = true;
|
||||
currentTime = 0;
|
||||
src = "";
|
||||
seekEnd = 0;
|
||||
plays = 0;
|
||||
get seekable() {
|
||||
const end = this.seekEnd;
|
||||
return { length: end > 0 ? 1 : 0, end: () => end };
|
||||
}
|
||||
play() {
|
||||
this.plays++;
|
||||
this.paused = false;
|
||||
return Promise.resolve();
|
||||
}
|
||||
pause() {
|
||||
this.paused = true;
|
||||
}
|
||||
load() {}
|
||||
removeAttribute(name: string) {
|
||||
if (name === "src") this.src = "";
|
||||
}
|
||||
fire(type: string) {
|
||||
this.dispatchEvent(new Event(type));
|
||||
}
|
||||
}
|
||||
|
||||
class FakeHls implements HlsPort {
|
||||
loaded: string | null = null;
|
||||
destroyed = false;
|
||||
audioTrack = 0;
|
||||
constructor(readonly handlers: HlsHandlers) {}
|
||||
load(url: string) {
|
||||
this.loaded = url;
|
||||
}
|
||||
destroy() {
|
||||
this.destroyed = true;
|
||||
}
|
||||
getAudioTrack() {
|
||||
return this.audioTrack;
|
||||
}
|
||||
setAudioTrack(track: number) {
|
||||
this.audioTrack = track;
|
||||
}
|
||||
levelInfo() {
|
||||
return { index: 0, total: 1 };
|
||||
}
|
||||
lost404() {
|
||||
this.handlers.onError({
|
||||
fatal: true,
|
||||
network: true,
|
||||
status: 404,
|
||||
type: "networkError",
|
||||
details: "fragLoadError",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
interface Ask {
|
||||
id: string;
|
||||
startAt: number;
|
||||
params: SessionParams;
|
||||
resolve(s: PlexPlaySession): Promise<void>;
|
||||
reject(e: unknown): Promise<void>;
|
||||
}
|
||||
|
||||
const flush = () => new Promise((r) => setTimeout(r, 0));
|
||||
|
||||
function setup(over: Partial<EngineDeps> = {}) {
|
||||
const media = new FakeMedia();
|
||||
const asks: Ask[] = [];
|
||||
const hlses: FakeHls[] = [];
|
||||
const stops: [string, string][] = [];
|
||||
let clock = 1_000_000;
|
||||
const state = { position: 0, duration: 3000, params: { multi: false, audio: null, aoff: 0 } };
|
||||
const engine = new HlsEngine({
|
||||
media: () => media as unknown as HTMLMediaElement,
|
||||
requestSession: (id, startAt, params) =>
|
||||
new Promise<PlexPlaySession>((res, rej) => {
|
||||
asks.push({
|
||||
id,
|
||||
startAt,
|
||||
params,
|
||||
resolve: async (s) => {
|
||||
res(s);
|
||||
await flush();
|
||||
},
|
||||
reject: async (e) => {
|
||||
rej(e);
|
||||
await flush();
|
||||
},
|
||||
});
|
||||
}),
|
||||
stopSession: (id, sid) => void stops.push([id, sid]),
|
||||
createHls: (h) => {
|
||||
const hls = new FakeHls(h);
|
||||
hlses.push(hls);
|
||||
return hls;
|
||||
},
|
||||
params: () => state.params,
|
||||
position: () => state.position,
|
||||
duration: () => state.duration,
|
||||
now: () => clock,
|
||||
statusOf: (e) => (e as { status?: number }).status,
|
||||
...over,
|
||||
});
|
||||
return {
|
||||
engine,
|
||||
media,
|
||||
asks,
|
||||
hlses,
|
||||
stops,
|
||||
state,
|
||||
advance: (ms: number) => void (clock += ms),
|
||||
};
|
||||
}
|
||||
|
||||
const hls = (id: string, start_s = 0, sid = `s-${id}-${start_s}`): PlexPlaySession => ({
|
||||
mode: "hls",
|
||||
url: `/hls/${id}/index.m3u8`,
|
||||
start_s,
|
||||
id: sid,
|
||||
});
|
||||
const direct = (id: string): PlexPlaySession => ({
|
||||
mode: "direct",
|
||||
url: `/media/${id}`,
|
||||
start_s: 0,
|
||||
});
|
||||
|
||||
describe("one request per item in flight", () => {
|
||||
it("queues a restart asked for while the start is out, and sends only the LAST target", async () => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
for (let t = 100; t <= 2000; t += 100) engine.seek("A", t);
|
||||
expect(asks.map((a) => a.startAt)).toEqual([0]);
|
||||
await asks[0]!.resolve(hls("A"));
|
||||
expect(asks.map((a) => a.startAt)).toEqual([0, 2000]);
|
||||
});
|
||||
|
||||
it("drops the stale answer it queued behind — it never attaches", async () => {
|
||||
const { engine, asks, hlses, media } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.seek("A", 500);
|
||||
await asks[0]!.resolve(hls("A", 0));
|
||||
expect(hlses).toHaveLength(0);
|
||||
await asks[1]!.resolve(hls("A", 500));
|
||||
expect(hlses).toHaveLength(1);
|
||||
expect(hlses[0]!.loaded).toBe("/hls/A/index.m3u8?t=500");
|
||||
expect(media.src).toBe("");
|
||||
});
|
||||
|
||||
it("still sends the queued target when the in-flight request fails, and shows no error for it", async () => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.seek("A", 700);
|
||||
await asks[0]!.reject({ status: 500 });
|
||||
expect(asks.map((a) => a.startAt)).toEqual([0, 700]);
|
||||
expect(engine.getSnapshot().error).toBeNull();
|
||||
});
|
||||
|
||||
it("sends another item's request at once, and drops the first item's queue", async () => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.seek("A", 900);
|
||||
engine.leaveItem();
|
||||
engine.start("B", 0);
|
||||
expect(asks.map((a) => [a.id, a.startAt])).toEqual([
|
||||
["A", 0],
|
||||
["B", 0],
|
||||
]);
|
||||
await asks[0]!.resolve(hls("A"));
|
||||
await asks[1]!.resolve(direct("B"));
|
||||
expect(asks).toHaveLength(2); // A's 900 is gone with A, whichever answer settles first
|
||||
});
|
||||
|
||||
it("never sends a queued target of an item the viewer left before the next one started", async () => {
|
||||
// The next item's detail may still be loading: nothing replaced the queue yet.
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.seek("A", 900);
|
||||
engine.leaveItem();
|
||||
await asks[0]!.resolve(hls("A"));
|
||||
expect(asks).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("reads the track parameters when the queued request is SENT", async () => {
|
||||
const { engine, asks, state } = setup();
|
||||
engine.start("A", 100);
|
||||
engine.start("A", 100); // an audio switch while the start is out
|
||||
state.params = { multi: false, audio: 1, aoff: 0 } as never;
|
||||
await asks[0]!.resolve(hls("A", 100));
|
||||
expect(asks[1]!.params.audio).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("answers that land late", () => {
|
||||
it("are dropped after the viewer moved to another item — and the server session is stopped", async () => {
|
||||
const { engine, asks, hlses, stops } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.leaveItem();
|
||||
engine.start("B", 0);
|
||||
await asks[1]!.resolve(direct("B"));
|
||||
await asks[0]!.resolve(hls("A", 0, "sA"));
|
||||
expect(hlses).toHaveLength(0);
|
||||
expect(stops).toEqual([["A", "sA"]]);
|
||||
});
|
||||
|
||||
it("are dropped after the player closed", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.start("A", 0);
|
||||
engine.destroy(media as unknown as HTMLMediaElement);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
expect(media.src).toBe("");
|
||||
});
|
||||
|
||||
it("land again once a StrictMode remount revived the engine", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.destroy(media as unknown as HTMLMediaElement);
|
||||
engine.revive();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
expect(media.src).toBe("/media/A");
|
||||
});
|
||||
|
||||
it("a superseded direct item's loadedmetadata does not seek the next one", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.start("A", 1200);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
engine.leaveItem();
|
||||
engine.start("B", 0);
|
||||
await asks[1]!.resolve(direct("B"));
|
||||
media.fire("loadedmetadata");
|
||||
expect(media.currentTime).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("the server session", () => {
|
||||
it("is stopped when the viewer leaves the item, and when the player closes", async () => {
|
||||
const { engine, asks, stops, media } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0, "sA"));
|
||||
engine.leaveItem();
|
||||
expect(stops).toEqual([["A", "sA"]]);
|
||||
engine.start("B", 0);
|
||||
await asks[1]!.resolve(hls("B", 0, "sB"));
|
||||
engine.destroy(media as unknown as HTMLMediaElement);
|
||||
expect(stops).toEqual([
|
||||
["A", "sA"],
|
||||
["B", "sB"],
|
||||
]);
|
||||
});
|
||||
|
||||
it("is not stopped by a restart of the same item — the server replaces it itself", async () => {
|
||||
const { engine, asks, stops } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0, "s1"));
|
||||
engine.seek("A", 2000);
|
||||
await asks[1]!.resolve(hls("A", 2000, "s2"));
|
||||
expect(stops).toEqual([]);
|
||||
});
|
||||
|
||||
it("is stopped when a direct stream of the same item replaces it", async () => {
|
||||
const { engine, asks, stops } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0, "s1"));
|
||||
engine.start("A", 0); // an A/V offset back at 0 plays the file directly
|
||||
await asks[1]!.resolve(direct("A"));
|
||||
expect(stops).toEqual([["A", "s1"]]);
|
||||
});
|
||||
|
||||
it("is stopped when Safari plays it natively too (no hls.js)", async () => {
|
||||
const { engine, asks, stops, media } = setup({ createHls: () => null });
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0, "sA"));
|
||||
expect(media.src).toBe("/hls/A/index.m3u8");
|
||||
engine.leaveItem();
|
||||
expect(stops).toEqual([["A", "sA"]]);
|
||||
});
|
||||
|
||||
it("is stopped on an unload, but not when the page goes into the back/forward cache", async () => {
|
||||
const { engine, asks, stops } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0, "sA"));
|
||||
engine.pageHidden(true);
|
||||
expect(stops).toEqual([]);
|
||||
engine.pageHidden(false);
|
||||
expect(stops).toEqual([["A", "sA"]]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("a failed session request", () => {
|
||||
it.each([
|
||||
[404, "notFound"],
|
||||
[501, "transcode"],
|
||||
[500, "generic"],
|
||||
] as const)("%s says %s", async (status, error) => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.reject({ status });
|
||||
expect(engine.getSnapshot().error).toBe(error);
|
||||
});
|
||||
|
||||
it("keeps the old stream's clock after a failed seek-restart, not after a failed move", async () => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
engine.seek("A", 2000);
|
||||
expect(engine.clockLive).toBe(false);
|
||||
await asks[1]!.reject({ status: 500 });
|
||||
expect(engine.clockLive).toBe(true);
|
||||
engine.leaveItem();
|
||||
engine.start("B", 0);
|
||||
await asks[2]!.reject({ status: 404 });
|
||||
expect(engine.clockLive).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("a session the server no longer has (404)", () => {
|
||||
it("is reclaimed where the viewer is", async () => {
|
||||
const { engine, asks, hlses, state } = setup();
|
||||
engine.start("A", 600);
|
||||
await asks[0]!.resolve(hls("A", 600));
|
||||
hlses[0]!.handlers.onManifestParsed();
|
||||
state.position = 1299;
|
||||
hlses[0]!.lost404();
|
||||
expect(asks[1]!.startAt).toBe(1299);
|
||||
});
|
||||
|
||||
it(`gives up after ${MAX_SESSION_RECLAIMS} reclaims inside the window, and says so`, async () => {
|
||||
const { engine, asks, hlses } = setup();
|
||||
engine.start("A", 600);
|
||||
for (let i = 0; i <= MAX_SESSION_RECLAIMS; i++) {
|
||||
await asks[i]!.resolve(hls("A", 600));
|
||||
hlses[i]!.lost404();
|
||||
}
|
||||
expect(asks).toHaveLength(MAX_SESSION_RECLAIMS + 1);
|
||||
expect(engine.getSnapshot().error).toBe("generic");
|
||||
});
|
||||
|
||||
it("rolls the window: losses closer than it keep counting, however slow", async () => {
|
||||
const { engine, asks, hlses, advance } = setup();
|
||||
engine.start("A", 600);
|
||||
for (let i = 0; i <= MAX_SESSION_RECLAIMS; i++) {
|
||||
await asks[i]!.resolve(hls("A", 600));
|
||||
hlses[i]!.lost404();
|
||||
advance(RECLAIM_WINDOW_MS * 0.6);
|
||||
}
|
||||
expect(engine.getSnapshot().error).toBe("generic");
|
||||
});
|
||||
|
||||
it("starts over for a loss long after the last one, and for a new item", async () => {
|
||||
const { engine, asks, hlses, advance } = setup();
|
||||
engine.start("A", 600);
|
||||
for (let i = 0; i < 4; i++) {
|
||||
await asks[i]!.resolve(hls("A", 600));
|
||||
hlses[i]!.lost404();
|
||||
advance(RECLAIM_WINDOW_MS + 1);
|
||||
}
|
||||
expect(engine.getSnapshot().error).toBeNull();
|
||||
const fresh = setup();
|
||||
fresh.engine.start("A", 0);
|
||||
for (let i = 0; i < MAX_SESSION_RECLAIMS; i++) {
|
||||
await fresh.asks[i]!.resolve(hls("A"));
|
||||
fresh.hlses[i]!.lost404();
|
||||
}
|
||||
fresh.engine.newItem();
|
||||
await fresh.asks[MAX_SESSION_RECLAIMS]!.resolve(hls("A"));
|
||||
fresh.hlses[MAX_SESSION_RECLAIMS]!.lost404();
|
||||
expect(fresh.engine.getSnapshot().error).toBeNull();
|
||||
});
|
||||
|
||||
it("keeps the start's own intent to play when it was lost before it ever played", async () => {
|
||||
const { engine, asks, hlses, media } = setup();
|
||||
engine.start("A", 600);
|
||||
await asks[0]!.resolve(hls("A", 600));
|
||||
hlses[0]!.lost404(); // media is still paused: not the viewer's pause
|
||||
await asks[1]!.resolve(hls("A", 600));
|
||||
hlses[1]!.handlers.onManifestParsed();
|
||||
expect(media.plays).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("play intent while a session is asked for", () => {
|
||||
it("goes into the pending session, and never plays the outgoing media", async () => {
|
||||
const { engine, asks, media, hlses } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
media.fire("loadedmetadata");
|
||||
expect(media.paused).toBe(false);
|
||||
engine.seek("A", 2000, false); // a restart while paused-by-request
|
||||
expect(engine.requestPlay(false)).toBe(true);
|
||||
expect(media.paused).toBe(true);
|
||||
const plays = media.plays;
|
||||
expect(engine.requestPlay(true)).toBe(true);
|
||||
expect(media.plays).toBe(plays); // the outgoing stream stays silent
|
||||
expect(engine.shownPlaying()).toBe(true);
|
||||
await asks[1]!.resolve(hls("A", 2000));
|
||||
hlses[0]!.handlers.onManifestParsed();
|
||||
expect(media.plays).toBe(plays + 1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("seeking", () => {
|
||||
it("a restart asked for before the new session has played keeps that session's intent to play", async () => {
|
||||
// Attaching a new session empties the media: it reads paused until hls.js parses and plays. A
|
||||
// seek in that window read the paused element as "the viewer paused", and the next session
|
||||
// attached paused at 0:00 (measured: a burst of ← ending in a frozen frame).
|
||||
const { engine, asks, hlses, media } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 0));
|
||||
expect(media.paused).toBe(true); // attached, not played yet
|
||||
engine.seek("A", 2000);
|
||||
await asks[1]!.resolve(hls("A", 2000));
|
||||
hlses[1]!.handlers.onManifestParsed();
|
||||
expect(media.paused).toBe(false);
|
||||
});
|
||||
|
||||
it("is native inside the attached session's loaded region", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 600));
|
||||
media.seekEnd = 100;
|
||||
engine.seek("A", 650);
|
||||
expect(asks).toHaveLength(1);
|
||||
expect(media.currentTime).toBeCloseTo(650 - (600 - HLS_SUB_LAG));
|
||||
});
|
||||
|
||||
it("restarts past it, and while the clock is not the current session's", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A", 600));
|
||||
media.seekEnd = 100;
|
||||
engine.seek("A", 900);
|
||||
expect(asks.map((a) => a.startAt)).toEqual([0, 900]);
|
||||
engine.seek("A", 650); // inside the OLD buffer, but a restart is pending
|
||||
await asks[1]!.resolve(hls("A", 900));
|
||||
expect(asks.map((a) => a.startAt)).toEqual([0, 900, 650]);
|
||||
});
|
||||
|
||||
it("clamps the target to the item", () => {
|
||||
const { engine } = setup();
|
||||
expect(engine.clamp(-5)).toBe(0);
|
||||
expect(engine.clamp(99_999)).toBe(2999);
|
||||
});
|
||||
});
|
||||
|
||||
describe("the session's clock", () => {
|
||||
it("folds hls.js's lag into a resumed HLS session's start, not a direct one's", async () => {
|
||||
const { engine, asks } = setup();
|
||||
engine.start("A", 600);
|
||||
await asks[0]!.resolve(hls("A", 600));
|
||||
expect(engine.getSnapshot().sessionK).toBeCloseTo(600 - HLS_SUB_LAG);
|
||||
engine.start("A", 0);
|
||||
await asks[1]!.resolve(direct("A"));
|
||||
expect(engine.getSnapshot().sessionK).toBe(0);
|
||||
});
|
||||
|
||||
it("is not trusted between asking for a session and its answer", async () => {
|
||||
const { engine, asks, media } = setup();
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
media.currentTime = 50;
|
||||
expect(engine.absTime(media as unknown as HTMLMediaElement)).toBe(50);
|
||||
engine.releaseClock();
|
||||
expect(engine.absTime(media as unknown as HTMLMediaElement)).toBeNull();
|
||||
});
|
||||
|
||||
it("answers 'where the viewer is' with the asked start before playback has ticked", () => {
|
||||
const { engine, state } = setup();
|
||||
engine.start("A", 1200);
|
||||
expect(engine.playhead()).toBe(1200);
|
||||
state.position = 1250;
|
||||
expect(engine.playhead()).toBe(1250);
|
||||
});
|
||||
});
|
||||
|
||||
describe("audio on a multi-rendition session", () => {
|
||||
it("restores the chosen track once hls.js lists the renditions, and switches client-side", async () => {
|
||||
const { engine, asks, hlses, state } = setup();
|
||||
state.params = { multi: true, audio: 1, aoff: 0 } as never;
|
||||
expect(engine.setAudioTrack(1)).toBe(false); // nothing attached yet: the caller restarts
|
||||
engine.start("A", 0);
|
||||
await asks[0]!.resolve(hls("A"));
|
||||
hlses[0]!.handlers.onAudioTracksUpdated();
|
||||
expect(hlses[0]!.audioTrack).toBe(1);
|
||||
expect(engine.setAudioTrack(0)).toBe(true);
|
||||
expect(hlses[0]!.audioTrack).toBe(0);
|
||||
expect(asks).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
it("tells React only when the snapshot really changed", async () => {
|
||||
const { engine, asks } = setup();
|
||||
const seen = vi.fn();
|
||||
engine.subscribe(seen);
|
||||
engine.start("A", 0);
|
||||
const after = seen.mock.calls.length;
|
||||
engine.start("A", 0); // same ready/error/transcode — nothing new to render
|
||||
expect(seen.mock.calls.length).toBe(after);
|
||||
await asks[0]!.resolve(direct("A"));
|
||||
});
|
||||
Reference in New Issue
Block a user