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
Co-authored-by: Timothy <timothy.look@gmail.com> Co-committed-by: Timothy <timothy.look@gmail.com>
117 lines
4.9 KiB
TypeScript
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');
|
|
}
|