Skip to content

Add add-device flow with manual-IP pairing and Tailscale support - #232

Merged
bitxeno merged 25 commits into
masterfrom
feat/add-device-flow
Oct 25, 2026
Merged

bitxeno merged 25 commits into
masterfrom
feat/add-device-flow

Conversation

@bitxeno

@bitxeno bitxeno commented Oct 25, 2026

Copy link
Copy Markdown
Owner

Why

atvloadly only discovered devices through mDNS/avahi on the local network, so the portal stopped working once a device was reachable only over a mesh VPN such as Tailscale (issue #223). This branch adds an add-device flow that lets an Apple TV or iPhone be entered by IP and reached over an overlay network, and hardens the dynamic port discovery it depends on.

It builds on the approach explored in #224 but replaces its port model: Apple's manual-pairing service is not on the fixed 62078 (that is lockdownd), and the install/tunnel service moves to a dynamic port on every service restart. Both are instead classified by the RPPairing handshake, which is fast, side-effect free and needs no pairing record.

Approach

  • Classify ports by handshake, not by guessing. A single RPPairing handshake probe reports allowsPairSetup (manual-pairing service) and allowsIncomingTunnelConnections (install/tunnel service). This is ~20 ms per port and works before any pairing record exists, so discovery no longer needs a saved plist or a plumesign device-info round trip per candidate.
  • Pipelined ascending scan with early exit. Ports are dialed in ascending order (Darwin allocates ephemeral ports low-first) at 128 concurrent dials, and the first handshake hit cancels the rest. This stays under the relay's SYN-burst limit that makes a 1024-way sweep miss the service entirely, and it skips the unicast mDNS query for CGNAT addresses that cannot answer it.
  • Cache the resolved port, but verify it cheaply. A resolved tunnel port is reused for 60 s; after that it is re-checked with a single handshake (full dial budget as the response deadline, retried a few times) before falling back to a full scan. The port only changes when the device restarts its services, so this avoids a multi-second sweep on every install.
  • Restrict manual addresses. Manual entry triggers a full-range scan, so only private LAN and CGNAT (100.64.0.0/10) addresses are accepted; public addresses are rejected rather than turned into an arbitrary scanner.

How it works

  • internal/manager/pairing_port_discovery.go — the RPPairing frame, handshake parser, unicast DNS-SD fast path and the pipelined ascending scan shared by manual-pairing and tunnel discovery. doc/misc/remote-pairing-port-discovery.md records the protocol measurements behind the tuning.
  • internal/manager/device_manager.go — manual devices are rebuilt from the pairing files, merged into GetDevices (a fresher mDNS entry wins), and get their tunnel port resolved through PrepareManualDevice with a per-device lock so concurrent install and refresh scan once. A stale mDNS entry is hidden by a liveness probe so its manual record takes over.
  • internal/service/websocket.go, web/router.go — manual pairing discovers the pairing port first and streams progress; /api/pair/tunnel-port resolves the tunnel port for the add-device page; every tunnel entry (install, refresh, mount, screenshot, AFC) resolves the port before dialing, and pairing warms it in the background.
  • web/static/src/page/add-device/ — the add-device page (Apple TV / iPhone tabs) plus the manual pairing page. The Wi-Fi root cause for iOS is surfaced in the tunnel-port error and the no_device copy instead of a modal reminder, since iOS only exposes its developer/lockdown services while on Wi-Fi.
  • internal/manager/device_probe.go, manual_device_test.go, pairing_port_discovery_test.go — liveness probing and coverage of the manual lifecycle, TTL reuse, remembered-port retries and the scan.

Links

Add a dedicated add-device page that replaces the pairable-device card on
the home sidebar with a persistent "Add New Device" entry.

The page offers two tabs:
- Apple TV (default, left): pick a discovered pairable Apple TV from a
  combobox and start the existing pairing flow; no port or pairing file.
- iPhone: pick an iPhone from a combobox and upload a pairing file, reusing
  the existing lab import flow.

Both device lists use a shared combobox (typing an IP is supported) with a
refresh button; the Apple TV list keeps its spinner up for at least one
second so the fast endpoint still gives visible feedback. Lists are filtered
to Apple TV / iPhone devices (unknown classes kept) and refreshed on tab
entry. Add the /add-device route, sidebar icons, and locale strings for all
bundled languages. Hide the service-status card on phones.
Stack the Anisette server presets (URL above name and default badge) and
let device names wrap instead of being clipped, with 44px tap targets and a
scrollable list under 767px. Desktop layout is unchanged.
Allow pairing an Apple TV entered by IP (e.g. over Tailscale) whose
pairing port is unknown. The pair page now discovers the manual-pairing
port first: the start button stays disabled until a port is found, shows
a progress panel (mDNS lookup, TCP scan percentage, service probe) and
offers a rediscover button.

Backend:
- Add RPPairing port discovery (handshake + unicast DNS-SD fast path +
  two-stage TCP scan) in internal/manager/pairing_port_discovery.go.
- Add Device.Manual; pass --manual to `plumesign pair` for manual IPs.
- Extend the pair websocket with t=3 (discover) and t=4 (start with ip+port);
  discovery streams JSON progress lines on the same socket.

Frontend:
- Pair page manual mode driven by ?ip= / the pair-manual route.
- add-device routes a typed IP that matches no discovered device into the
  manual pairing flow instead of erroring.

Includes Go unit tests (frame/parse/mock-server/scan) and a frontend test
for the discovery messages and start payload.
Let the add-device iPhone tab connect an iPhone typed by IP whose
_remotepairing tunnel port is unknown.

Backend:
- Generalize port discovery with a shared predicate-based scanner and add
  DiscoverManualTunnelPort (unicast _remotepairing._tcp + TCP scan picking
  allowsIncomingTunnelConnections).
- Pass --manual through ImportPairingFile (manager/service/router) so
  `plumesign check pairing` knows the IP was entered manually.
- Add GET /api/pair/tunnel-port?ip= returning the discovered tunnel port
  (IPv4-only).

Frontend:
- api.discoverTunnelPort; iPhone startConnect uses a discovered device's
  port when present, otherwise probes the tunnel port and imports with
  manual=true. Button spinner covers probe+import; failures show a toast.
- Rewrite the iPhone no_device text to tunnel-service semantics (5 locales).

Tests: tunnel discovery (picks tunnel, ignores pair-setup), pairingCheckArgs
--manual, and a frontend test for the discovered/manual/failure branches.
Manual / Tailscale devices do not broadcast mDNS, so they never reached the
device list. Read them directly from the pairing files instead of adding a
new store: the .json peer record already carries manual, remotepairing_ip,
name, model and udid.

Backend:
- RemoteDevice gains Manual and RemotePairingIP.
- DeviceManager keeps a separate manualDevices map loaded from
  <pairing_files>/*.json (manual=true + remotepairing_ip) and merges it into
  GetDevices, deduped by UDID with mDNS entries winning. ReloadDevices
  refreshes it; Scan() leaves it intact.
- DeleteManualDevice removes both <udid>.json and <udid>.plist and the
  in-memory entry; POST /api/devices/:id/manual/delete exposes it.

Frontend:
- Manual devices show status "已添加" (added) and an "IP" badge on the icon's
  top-right corner (brand blue) instead of the online dot; IP stays after the
  name. A "忘记" action with click-to-confirm deletes the pairing files.

Tests: manual device loading/skip, dedupe with discovered, file deletion.
Port probing for install is deferred to a later step.
- Move the "IP" badge onto .avatar instead of .avatar > div, which daisyUI
  clips with overflow:hidden, so the badge is no longer cut off.
- Float the forget button to the far right of the row and show it only on
  row hover (or keyboard focus / armed state); on phones (<=767px) it stays
  always visible and the row wraps so it never overlaps the device text.
Take the forget button out of the row's flex flow (position: absolute at the
right edge) so the device title keeps the full width and never reflows to make
room for it. Hidden until row hover on desktop; always visible on phones with
reserved right padding so it does not cover the text.
- Move the manual-device forget button inline right after the status text
  ("已添加 · RPPairing") instead of floating at the row's right edge, so it
  never competes with the title for space.
- Change the forget/delete tooltip to "删除设备" (Delete device) across
  locales.
Replace the delete icon with an underlined "删除" text link on the status
line, prefixed by a "·" separator that only appears on row hover. The link
defaults to the danger color; the underline lives on an inner label so the
separator dot stays clean. Always visible on phones.
Manual (pairing-file/Tailscale) devices carry no tunnel port, so every flow
that reached them over RSD failed. Resolve the dynamic _remotepairing port on
demand (60s cache, per-UDID mutex, no automatic retry) and inject it before
use.

- manager.PrepareManualDevice / ManualPortNeedsResolve: probe the tunnel port
  for manual devices only, cache it on the in-memory device (PortResolvedAt),
  preserve it across pairing-file reloads, and serialize concurrent probes.
- Install: prepare before the queue (task.runInternal), interactive websocket
  (runInstallMessage) and external-certificate (runExternalInstall) paths; the
  install log shows "Resolving tunnel port for manual device...".
- Refresh: manager.CheckAfcServiceStatus prepares the port first, covering the
  cron schedule, device-triggered refresh and /api refresh. Manual devices rely
  on the cron schedule (no mDNS connect event).
- Mount/screenshot: prepare the port before RSD commands.

Tests: port resolution, no-op for discovered devices, TTL reuse/expiry, error
keeps port 0, and concurrent single-probe.
A device that leaves the network without an mDNS goodbye stayed in the
discovery map forever and shadowed its manual (pairing-file) record. Add a
background liveness loop for devices that have BOTH an mDNS entry and a manual
record:

- Every minute, TCP-dial the tunnel port of dual-source remote devices that
  have not been probed in the last minute; a fresh mDNS announcement counts as
  a probe. Lockdown/USB, pairable and port-less entries are never probed.
- After 5 consecutive failures the device is marked stale (hidden from
  GetDevices) so the manual entry surfaces; a later successful probe or a new
  announcement clears the flag and mDNS wins again.
- Stale is a flag, not a delete, so avahi never needs to re-announce for the
  device to come back.

Constants (interval, min age, fail threshold, dial timeout) are grouped at the
top of device_probe.go for easy tuning. Adds unit tests for targeting,
min-age skip, threshold/recovery and announcement reset.
discoverTunnelPort now sends silent:true so the request interceptor does not
toast the API error, leaving only the page's own "tunnel service not found"
message. The response interceptor's network-error branch also honours
silent so a timeout cannot double-toast either.
Error toasts used the global 3s autoClose and were easy to miss. Wrap
toast.error once at startup so error toasts default to 6s while success and
other toasts keep the global 3s; an explicit autoClose in a call still wins.
Drop the request interceptor's own 5s override so API errors use the same
default.
Switching tabs reuses the cached device list instead of reloading
every time; a failed load still retries on the next switch. The
combobox refresh button keeps reloading on demand.
…go build

Move the bitxeno/bom fork (pinned at 0e05147) into pkg/bom as a nested
module and swap its cgo github.com/blacktop/lzfse-cgo dependency for
bitxeno/lzfse-go, which calls the native lzfse through purego from an
embedded shared library. Decoded pixels are verified identical to the
cgo version on a real Assets.car.

With the last hard cgo dependency gone the whole service builds with
CGO_ENABLED=0, which the release and nightly xgo workflows already set.
At 250ms the dial budget matched the Tailscale relay RTT, so the open
service ports that need a full handshake were often missed under the
1024-concurrent scan, making tunnel discovery fail intermittently with
"manual tunnel port not found". 600ms leaves room for the measured
100-250ms relay latencies, as the design doc already recommended for
full port lists.
Ports are dialled in ascending order and probed as soon as each dial succeeds; the first matching RPPairing service cancels the rest of the scan. Darwin allocates ephemeral ports ascending, so the tunnel port sits near 49152 in practice and is found without sweeping the full range: ~0.9s vs ~5s to a real device over Tailscale.

Unicast mDNS is skipped for 100.x.x.x addresses (Tailscale CGNAT range): the query can never cross the overlay tunnel and only cost its 1.5s timeout.

Two scan stalls surfaced by this change are also fixed: silent local listeners (rapportd, the app's own HTTP server) accept the probe and answer nothing, so the handshake response deadline is now 800ms separate from the 2s dial timeout, and the probe pool is widened to 32 slots so a handful of such listeners cannot starve the real service.
DiscoverManualPairingPort now shares the pipelined ascending scan and the 100.x.x.x mDNS skip with the tunnel discovery, instead of its own full-range collect-all scan. The tunnel port it reported was never consumed by the pair page, so the field and the collect-all variant are removed.

Scan concurrency rises to 1536 (doc-proven stable) because Apple devices silently drop SYNs to closed ports, making a full sweep timeout-bound: a paired Apple TV outside pairing mode is found in ~4.3s instead of ~8.7s on LAN, while the Tailscale tunnel path stays at ~0.9-1.6s.
WebKit moves focus on mousedown, so clicking an option blurred the
input and closed the dropdown before the click could land on the
button: the click retargeted to the enclosing form and the selection
was lost (Safari and the desktop webview). Prevent the default on
mousedown in both comboboxes — DeviceComboBox and the settings
anisette server list — so the input keeps focus until pick runs.
Verified in headless WebKit and Chromium with real click sequences.
Full-range probes from the Docker deployment failed most of the time against a Tailscale device: a burst of 1536 concurrent SYNs saturates the relay queue, and the open service port itself starts exceeding the dial timeout. In-container measurements showed 2 of 3 scans missing the port entirely, while a single unthrottled dial always succeeded (0.3-1.1s RTT).

The scan now dials 128 ports per 1.5s wave: closed ports answer RST fast, every sweep found the service (5/5 in-container runs, 1.6-1.8s for the common low-port case), and the ascending order with early exit keeps high ports reachable on later waves.

PrepareManualDevice additionally re-probes the remembered port with a single handshake before falling back to the scan, since the tunnel port only changes when the device restarts its services: repeated installs hit a 3.25us cache path or one 2s dial instead of a full sweep.
Replace the Apple TV and iPhone tab glyphs on the add-device page with
outline icons sourced from Icon=appletv.svg and Icon=ipad.and.iphone.svg.
Both are drawn with fill="currentColor", so they follow the button text
colour and turn white when the tab is selected (btn-primary).

The iPhone glyph keeps the iPad knockout behind the phone via an SVG
mask instead of the original white fill, so the overlap stays clean on
both the light and the selected blue background.
The badge used --atv-accent-soft, which is nearly the same shade as the
row hover tint (--atv-surface-hover), so the icon all but disappeared
when the add-device row was hovered.

Add an --atv-accent-soft-hover token for light and dark themes and apply
it to the badge while its row is hovered, with a short transition.
Connecting to an iPhone via a 100.x.x.x (Tailscale) address only works
while the iPhone is on Wi-Fi. Show a confirmation dialog with Cancel and
Continue before starting the connect flow when a Tailscale IP is entered.

- Detect 100.x.x.x addresses and gate the connect flow on a reminder dialog
- Split startConnect into the reminder gate and connectIPhone worker
- Add tailscale_wifi strings to all bundled locales
- Cover the reminder, confirm and cancel paths in tests
- Restrict manual device addresses to private LAN and CGNAT
  (100.64.0.0/10) so a manual entry can no longer trigger a full-range
  scan of arbitrary public hosts.
- Warm the tunnel port in the background after pairing completes, so the
  first install skips the full-range scan.
- Re-check a remembered port with the full dial budget as its handshake
  deadline and retry a few times, so one slow relay round trip no longer
  turns a healthy device into a multi-second full-range scan.
- Raise the scan handshake response deadline to 1.2s and the tunnel-port
  API budget to 30s to cover relay RTT.
- Drop the Tailscale Wi-Fi reminder dialog and fold the Wi-Fi root cause
  into the tunnel-port error and the no_device copy (all locales).
@bitxeno
bitxeno merged commit c77fae6 into master Oct 25, 2026
2 checks passed
bitxeno added a commit that referenced this pull request Oct 25, 2026
Bring in the add-device flow and the hardened manual (Tailscale) port
discovery, plus the pkg/bom vendoring that master picked up from this
branch's history.

Conflict resolution:

- internal/manager/*, internal/model/pairing_discovery.go, web/router.go,
  internal/service/websocket.go: take master. Both sides descend from the
  same add-device work, and master's c77fae6 is the squashed PR #232 which
  contains the hardened discovery (pipelined scan, CGNAT-aware address
  check, DiscoverManualTunnelPort, WarmManualDevicePort). This branch's
  copies were an earlier snapshot of that work, so master's version is a
  strict superset.
- locales/*.json: keep both sides. This branch added the desktop "tray"
  block, master reworded addDevice.iphone.no_device.
- web/static/src/page/*: take master (same earlier-snapshot situation).

Nothing under desktop/, internal/bootstrap or cmd/ was touched by master,
so the desktop app is unaffected.

Verified: go build ./..., go test ./..., golangci-lint run (0 issues),
the desktop module build, and the web/static production build.
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

⌂ 换网址