Files
ersatztv/web/src/mediaSources/pinFlowPoll.ts
T
timothy 11ec07ee1b
Build ErsatzTV Image / CI image pin matches docker/ci (push) Has been skipped
Build ErsatzTV Image / decisions.md append-only (push) Has been skipped
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (push) Has been skipped
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (push) Has been skipped
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Successful in 6m10s
Build ErsatzTV Image / Build & push image (amd64) (push) Has been skipped
Build ErsatzTV Image / Functional E2E (curl contracts) (push) Successful in 14m38s
Build ErsatzTV Image / Build & test (.NET) (push) Successful in 20m18s
Build ErsatzTV Image / Docs update reminder (push) Has been skipped
fix(367): correct Plex budget-exhausted guidance when no servers exist (#450)
Co-authored-by: Timothy <timothy.look@gmail.com>
Co-committed-by: Timothy <timothy.look@gmail.com>
2026-07-18 16:15:37 +00:00

117 lines
4.9 KiB
TypeScript

// The Plex OAuth pin-flow poll STATE MACHINE (design §C1 step 5), as a pure, timer-free module so
// the transitions can be unit-tested with injected state. The Plex screen (slice S6b) drives it:
// after `POST /pin-flow` it opens the auth URL and polls `GET /api/v1/media-sources/plex` every 2s for
// up to 150s, feeding each observation ({ isLocked, isAuthorized, hasServers }) here to decide what to
// show and whether to keep polling.
//
// KEY INSIGHT (finding 5): `isAuthorized` flips true the moment the token is saved, which is BEFORE
// SynchronizePlexMediaSources discovers the servers and releases the Plex lock. So authorization
// alone is NOT success — the terminal success signal is the lock RELEASING while authorized. Poll
// until the lock releases, not until authorized.
//
// AUTHORIZED-BUT-EMPTY (#345): authorization and server discovery are distinct outcomes. A real flow
// reached `isAuthorized: true`, `isLocked: false`, `servers: []` (a Plex account that owns/has been
// granted no eligible servers). That is a coherent, recoverable terminal — NOT "Connected to Plex." —
// so the released-lock success branch further splits on whether any server was actually discovered.
//
// isLocked & !isAuthorized -> waiting (keep polling; user hasn't authorized yet)
// isLocked & isAuthorized -> finalizing (keep polling; discovering servers)
// !isLocked & isAuthorized & servers -> success (terminal; connected to a server)
// !isLocked & isAuthorized & !servers -> authorized-no-servers (terminal; authorized, none discovered)
// !isLocked & !isAuthorized -> timeout (terminal; flow ended without auth)
// isLocked (budget spent) -> budget-exhausted (terminal; a large first sync legitimately
// still holds the lock — not a failure)
export type PinFlowStatus =
| 'waiting'
| 'finalizing'
| 'success'
| 'authorized-no-servers'
| 'timeout'
| 'budget-exhausted';
export interface PinFlowObservation {
isLocked: boolean;
isAuthorized: boolean;
/** Whether server discovery has surfaced at least one server for this authorization. */
hasServers: boolean;
}
export interface PinFlowState {
status: PinFlowStatus;
/** True once the machine has settled and polling should stop. */
done: boolean;
/** True only on the successful terminal state. */
ok: boolean;
/** User-facing message for the current state. */
message: string;
}
/** Poll cadence and total budget (design §C1: every 2s for up to 150s). */
export const PIN_FLOW_POLL_INTERVAL_MS = 2000;
export const PIN_FLOW_POLL_BUDGET_MS = 150_000;
const MESSAGES: Record<PinFlowStatus, string> = {
waiting: 'Waiting for you to authorize in the Plex tab…',
finalizing: 'Authorized — discovering your Plex servers…',
success: 'Connected to Plex.',
'authorized-no-servers': 'Signed in to Plex, but no eligible servers were discovered.',
timeout: 'Plex sign-in timed out — try again.',
'budget-exhausted': 'Still working — this can take a while on a large first sync. Check again to see if it finished.'
};
const TERMINAL: ReadonlySet<PinFlowStatus> = new Set<PinFlowStatus>([
'success',
'authorized-no-servers',
'timeout',
'budget-exhausted'
]);
function stateFor(status: PinFlowStatus): PinFlowState {
return {
status,
done: TERMINAL.has(status),
ok: status === 'success',
message: MESSAGES[status]
};
}
/** The state shown before the first poll observation arrives. */
export function initialPinFlowState(): PinFlowState {
return stateFor('waiting');
}
/** True when the elapsed poll time has consumed the whole budget. */
export function isPinFlowBudgetExhausted(elapsedMs: number): boolean {
return elapsedMs >= PIN_FLOW_POLL_BUDGET_MS;
}
/**
* Evaluate a single poll observation. `budgetExhausted` reflects whether the poll budget is spent;
* it only matters while the lock is still held (a released lock is always terminal, success or
* timeout, regardless of budget).
*/
export function evaluatePinFlow(
observation: PinFlowObservation,
options: { budgetExhausted?: boolean } = {}
): PinFlowState {
const { isLocked, isAuthorized, hasServers } = observation;
// Lock released: terminal. Not authorized at all -> timeout. Authorized -> success only when a
// server was actually discovered; authorized-but-empty is its own recoverable terminal (#345).
if (!isLocked) {
if (!isAuthorized) {
return stateFor('timeout');
}
return stateFor(hasServers ? 'success' : 'authorized-no-servers');
}
// Still locked but out of budget: not a failure, just "still working".
if (options.budgetExhausted) {
return stateFor('budget-exhausted');
}
// Still locked, budget remaining: waiting for auth, or finalizing after auth.
return stateFor(isAuthorized ? 'finalizing' : 'waiting');
}