Send the mDNS PTR record lifetime, not its remaining TTL

[bdraco]

What does this implement/fix?

Follow-up to #1682. That PR shipped mdns_ptr_ttl_remaining_seconds plus a devices/get_reachability one-shot command so the drawer could poll the PTR's remaining TTL. Testing the live drawer showed the remaining TTL reads out of sync with "last seen": the drawer actively probes the A record (keeping last-seen fresh) while the PTR's remaining TTL is only refreshed by the zeroconf browser at ~80% of the lifetime, so the countdown drifted against last-seen.

This sends the PTR's full announced lifetime instead, mdns_ptr_ttl_seconds (= ptr.ttl, the device's own record lifetime), and the frontend derives the offline countdown as that lifetime minus the last-seen age, so the two move in lockstep on every subscription push. That makes the poll unnecessary, so devices/get_reachability is removed; no extra mDNS traffic is generated.

Related issue or feature (if applicable):

• part of [Bug] #1675

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: Show an mDNS record expiry countdown in the device drawer device-builder-frontend#969

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.index.json / definitions/components/*.json have not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks

---

_{Comparing mdns-expiry-from-last-seen (e27bda7) with main (584d722)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.54%. Comparing base (584d722) to head (e27bda7).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1685      +/-   ##
==========================================
- Coverage   99.54%   99.54%   -0.01%     
==========================================
  Files         227      227              
  Lines       18142    18134       -8     
==========================================
- Hits        18060    18052       -8     
  Misses         82       82              

Flag	Coverage Δ
py3.12	99.52% <100.00%> (-0.01%)	⬇️
py3.14	99.54% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
..._builder/controllers/_device_state_monitor/mdns.py	99.36% <100.00%> (ø)
...evice_builder/controllers/_reachability_tracker.py	100.00% <100.00%> (ø)
...e_device_builder/controllers/devices/controller.py	99.73% <ø> (-0.01%)	⬇️
esphome_device_builder/models/devices.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR updates the device reachability payload to send the mDNS PTR record’s full announced lifetime (mdns_ptr_ttl_seconds) rather than its remaining TTL, so the frontend can derive an “offline in N” countdown from the PTR lifetime minus “last seen” age (removing the need for polling).

Changes:

• Replace mdns_ptr_ttl_remaining_seconds with mdns_ptr_ttl_seconds throughout the reachability snapshot/event payload.
• Remove the devices/get_reachability one-shot WS command (polling no longer needed).
• Update API docs and adjust/remove tests accordingly.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
esphome_device_builder/controllers/_device_state_monitor/mdns.py	Emit PTR announced TTL (ptr.ttl) instead of remaining TTL in get_mdns_cache_info.
esphome_device_builder/controllers/_reachability_tracker.py	Rename snapshot field to mdns_ptr_ttl_seconds and propagate into the wire snapshot.
esphome_device_builder/models/devices.py	Update DeviceReachabilityData TypedDict field name to mdns_ptr_ttl_seconds.
esphome_device_builder/controllers/devices/controller.py	Remove the devices/get_reachability API command.
docs/API.md	Update devices/subscribe_reachability documentation and remove the devices/get_reachability entry.
tests/test_state_monitor_reachability.py	Update assertions to validate PTR lifetime instead of remaining TTL.
tests/test_reachability_tracker.py	Update snapshot expectations for renamed PTR TTL field.
tests/controllers/devices/test_subscribe_reachability.py	Remove coverage for the deleted devices/get_reachability command.

[esphbot]

Previous review — superseded by a newer review below.

[esphbot]

No blocking issues found.

[esphbot]

PR Review — Send the mDNS PTR record lifetime, not its remaining TTL

Clean, well-tested follow-up. Merge-ready; only a minor docstring-style nit.

Strengths:

• The mdns_ptr_ttl_remaining_seconds → mdns_ptr_ttl_seconds rename is applied consistently across the TypedDict, dataclass, snapshot builder, mdns reader, docs, and tests — no dangling references. Verified get_reachability_snapshot (controller.py:1103) is a separate, retained method still wired into reachability.py; only the get_reachability command is removed.

• The value change is correct: ptr.ttl is the constant announced lifetime, so the test rightly drops the flaky pytest.approx(..., abs=1.0) timing tolerance for an exact == 4500.0.

• docs/API.md is updated in lockstep, including corrected field semantics.

• Suggestion: the MdnsCacheInfo docstring (and matching mdns.py comment) carry drift rationale that repo style wants out of docstrings — non-blocking, partly pre-existing.

• Note: dropping a WS command shipped in Expose the mDNS PTR record TTL on the reachability snapshot #1682 is a public-API removal, but it's coordinated with frontend PR Enable SLOT (flake8-slots) ruff rule #969 and the feature is early beta, so acceptable.

---

---

Checklist

• Field rename applied consistently, no dangling references
• PTR lifetime value semantics correct (ptr.ttl vs get_remaining_ttl)
• Docs (API.md) updated to match
• Test coverage updated for renamed field and removed command
• Docstring/comment style (contract-focused, no rationale)
• Public-API removal coordinated with frontend

---

Automated review by Kōan (Claude) HEAD=e27bda7 1 min 11s

[esphbot]

No blocking issues found.