fix(plex): match server by /identity machineIdentifier for hostname URLs by engels74 · Pull Request #74 · edbfi/obzorarr

engels74 · 2026-04-18T22:50:35Z

Summary

When PLEX_SERVER_URL is a hostname (e.g. http://plex.local.timo.be:32400, a LAN DNS name, or a reverse-proxied URL) and the Plex server advertises only .plex.direct connection URIs under the signed-in user's Plex.tv resources list, Obzorarr's four URL-string matching strategies all fail and verifyServerMembership returns { isMember: false }. The user sees a greyed-out Continue button with no actionable error message and cannot complete onboarding.

The authoritative test is not URL-string matching — Obzorarr already reaches the configured server successfully, so it can ask the server for its own identity via GET /identity and match the returned machineIdentifier against each Plex.tv resource's clientIdentifier. This is the same value Plex itself uses for server identity and matches regardless of how the URL is expressed.

Changes

New Strategy 0: match by machineIdentifier from /identity

New service src/lib/server/plex/server-identity.service.ts exposes fetchServerIdentity(), getConfiguredServerMachineId() (cache-first), and refreshConfiguredServerMachineId() (force refresh). Uses a 10 s AbortController timeout and the existing classifyConnectionError helper.
src/lib/server/auth/membership.ts prepends a new matching strategy that compares the fetched machineIdentifier against each server's clientIdentifier. The existing four URL-based strategies remain as fallbacks for when /identity is unreachable.
MembershipResult gains a discriminated reason?: 'not_reachable' | 'not_in_resources' | 'not_owner' and configuredMachineId?: string so the UI can render specific messages and offer an explicit ownership override.

Cache + invalidation

app_settings gains a SERVER_MACHINE_ID row, mirroring the existing SERVER_NAME cache (getCachedServerMachineId / setCachedServerMachineId / clearCachedServerMachineId).
The admin settings form invalidates the cache whenever PLEX_SERVER_URL or PLEX_TOKEN changes so the next membership check re-fetches /identity.

Onboarding UX

src/routes/onboarding/plex/+page.server.ts proactively calls getConfiguredServerMachineId() in load and returns configuredUrlReachable, configuredUrlErrorReason, and configuredMachineId so the page can warn before the user signs in.
New forceManualSelection action sets an app-settings flag that forces the manual server picker on the next load; src/routes/onboarding/+layout.server.ts respects the flag.
New confirmOwnershipOverride action: when /identity succeeded but Plex.tv does not list the server for the signed-in user, the user can explicitly attest ownership to bypass the resources check. Logged at logger.warn with URL, machineId, and username for audit trail.
src/routes/onboarding/plex/+page.svelte renders specific error cards with remediation buttons instead of the previous silent disabled state.

Tests

tests/unit/auth/membership.test.ts — four new cases covering Strategy 0 match, fallback when /identity unreachable, not_in_resources with machineId, and the cache interaction.
tests/unit/plex/server-identity.service.test.ts — new file covering the valid response, missing friendlyName, 401 / non-401 HTTP errors, AbortError classification, URL trailing-slash normalization, cache hit/miss, and the force-refresh path.

Reproduction and verification

Bug reproduced locally against a Bun proxy (/tmp/plex-proxy.ts) that forwards a plain http://localhost:7777 origin to the live Plex server. Pre-fix, the logs show the exact failure from the upstream issue:

[Membership] Configured PLEX_SERVER_URL: http://localhost:7777 (source: env)
[Membership] Found 1 server(s) accessible to user
[Membership] Server: PARENTi | clientIdentifier: <id> | owned: true
[Membership]   - Connection URI: https://<ip>.<hash>.plex.direct:32400 ...
[Membership] No matching server found for configured URL

Sign-in throws NotServerMemberError and the onboarding page renders the authentication-failure card:

Pre-fix, onboarding step 2 leaves the user stuck at CONNECT (URL blurred):

Post-fix, with the same hostname-only PLEX_SERVER_URL, Strategy 0 fetches /identity, matches the returned machineIdentifier against Plex.tv resources, and the user advances to SYNC:

Test plan

bun run check — 0 errors
bun run test — full suite passes, new tests included, coverage ≥ 80 %
bun run check:biome — lint + format clean
Manual repro against live Plex server via local proxy: pre-fix blocks on CONNECT with No matching server found; post-fix matches via machineIdentifier and advances to SYNC
Manual unreachable-URL path: error card appears before sign-in with specific reason, forceManualSelection button falls back to manual picker
Cache invalidation on PLEX_SERVER_URL / PLEX_TOKEN change in admin settings

Hostname-based PLEX_SERVER_URL values (e.g. http://plex.local.timo.be:32400) failed membership matching when the server only advertised .plex.direct URIs, leaving users stuck on onboarding step 2. Add Strategy 0 in findConfiguredServer that fetches /identity and compares the returned machineIdentifier against each resource's clientIdentifier. Cache the configured machineId in app_settings and invalidate on URL/token change. Surface granular membership failure reasons (not_reachable / not_in_resources / not_owner) and expose them in onboarding: show a reachability error card with a "Use a different server" fallback, and — only when /identity succeeds but Plex.tv doesn't list the server — an explicit "I confirm I own this server" override that logs an audit warn. Fixes edbfi/obzorarr-docker#5.

augmentcode · 2026-04-18T22:55:17Z

🤖 Augment PR Summary

Summary: Fixes Plex onboarding failures when PLEX_SERVER_URL is a hostname/reverse-proxy URL by identifying the configured server via GET /identity and matching its machineIdentifier against Plex.tv resources.

Changes:

Adds SERVER_MACHINE_ID app-setting cache with helpers to get/set/clear it
Introduces server-identity.service.ts to fetch/parse /identity with a 10s abort timeout and sanitized error classification
Prepends “Strategy 0” in verifyServerMembership() to match servers by machine id (case-insensitive), then falls back to prior URL strategies
Adds a reachability gate: if /identity fails, membership now returns reason: 'not_reachable' instead of allowing URL-only matches
Threads structured failure reasons (not_reachable, not_in_resources, not_owner) and configuredMachineId through MembershipResult and improves user-facing failure messages
Updates onboarding to proactively probe reachability, show targeted error cards, and support a guarded ownership override flow during initial setup
Clears/invalidates the machine-id cache when Plex URL/token changes (admin settings, onboarding server selection, env-conflict cleanup)
Adds unit coverage for the new identity service and the updated membership strategy/gating behavior

Technical Notes: Membership checks now always perform a live /identity probe (refresh) to avoid admitting users based on stale cached ids after server/token changes.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 3 suggestions posted.