Skip to content

feat: start healthy and retry when Plex is unreachable at boot#302

Merged
cplieger merged 2 commits into
mainfrom
feat/degraded-plex-start
Jul 10, 2026
Merged

feat: start healthy and retry when Plex is unreachable at boot#302
cplieger merged 2 commits into
mainfrom
feat/degraded-plex-start

Conversation

@cplieger

Copy link
Copy Markdown
Owner

Summary

Makes plex-language-sync survive a Plex that is down at boot instead of crash-looping, and enrolls it on the shared image-smoke harness.

Previously the initial Plex connect + admin resolution exited non-zero on any failure, so under restart: unless-stopped a Plex outage at startup crash-looped the container. Startup now classifies the failure (mirroring plex-exporter):

  • Fatal (bad PLEX_TOKEN/4xx, wrong-server 404, TLS/cert error) -> exit non-zero; the container never goes healthy, so the misconfiguration stays loud.
  • Transient (Plex unreachable, DNS/timeout, or 5xx) -> mark the container healthy-degraded and retry the initial connect with capped exponential backoff (1s->30s) until Plex answers, then resolve the admin and begin normal operation.

WebSocket disconnects after the initial connect are unchanged (the listener already reconnects with backoff).

Changes

  • internal/plex/client.go: add a typed HTTPStatusError (carries the status code; message text unchanged) so the classifier can distinguish 4xx from 5xx.
  • main.go: connectAndResolveAdmin retry-until-connected loop + isFatalStartupError classifier + capped backoff; DeriveKey moved ahead of the connect so a bad token is surfaced before any healthy-degraded marking.
  • main_test.go: table test for the classifier + backoff.
  • README health section updated for the new semantics.

Smoke test

Enrolls plex-language-sync on the shared configs/image-smoke.sh harness (tests/image-smoke.conf, env-only dummy PLEX_URL/token). Validated locally: the image builds and the harness reports healthy after 5s against an unreachable Plex. Removes plex-language-sync's documented smoke-test exception.

Verification

go build, go vet, go test -race ./..., and golangci-lint run / fmt --diff all clean.

cplieger added 2 commits July 10, 2026 18:49
The initial Plex connect + admin resolution previously exited non-zero on any failure, so a Plex that was down at boot crash-looped the container under the restart policy. Now the startup classifies the failure: a fatal misconfiguration (bad token / 4xx, wrong-server 404, or a TLS/cert error) still exits non-zero, but a transient failure (Plex unreachable, DNS/timeout, or 5xx) marks the container healthy-degraded and retries the initial connect with capped exponential backoff (1s->30s) until Plex answers. This mirrors plex-exporter's fatal-vs-transient split and makes the container survive a Plex restart instead of crash-looping.

Adds a typed plex.HTTPStatusError (carrying the status code, message unchanged) so the classifier can tell 4xx from 5xx, and a table test for the classifier + backoff.
Now that a transient connect failure starts the container healthy-degraded (previous commit), plex-language-sync can reach healthy in CI against an unreachable dummy Plex. Enroll it on the shared harness: tests/image-smoke.conf (env-only, PLEX_URL=http://127.0.0.1:1 + a dummy token) + the canonical tests/image-smoke.sh synced from cplieger/ci. Removes plex-language-sync's documented smoke-test exception.
@cplieger cplieger enabled auto-merge (rebase) July 10, 2026 16:51
@cplieger cplieger merged commit df91623 into main Jul 10, 2026
16 checks passed
@cplieger cplieger deleted the feat/degraded-plex-start branch July 10, 2026 16:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant