Repository navigation
fix(tailnet): decode the tailscale CLI as utf-8, not the host code page - #14648
Conversation
Both tailscale spawns run in text mode with no `encoding=`, so the child's output is decoded with `locale.getpreferredencoding()` -- UTF-8 on POSIX, but the legacy ANSI code page on Windows. Tailnet device names are operator-chosen free text, and `tailscale ... --json` is JSON, which is defined as UTF-8 (RFC 8259 s8.1), so the correct decode is known rather than guessed. Both sites now splat `UTF8_TEXT`, the mapping this repository already uses for children whose encoding is knowable. Two distinct failures, measured rather than assumed: * Bytes that are also legal in the host code page decode to *different characters*, silently. A device named `測試-desk` comes back as other CJK characters on a cp950 host, and `_valid_magicdns_name` then rejects a name that was valid -- the tailnet origin is simply never derived. * Bytes that decode under neither take a platform-specific path, and neither one is caught. On POSIX `subprocess.run` raises `UnicodeDecodeError`, which is a `ValueError` and so passes straight through `except (OSError, subprocess.SubprocessError)`. On Windows `capture_output` reads on a helper thread, so the same error kills that thread, prints a traceback to the gateway's stderr, and leaves `proc.stdout` as `None`. Both break the contract `_run_json_detail` documents in its own docstring -- "``None`` on ANY failure ... every failure mode here means the same thing" -- by either answering wrongly or escaping. `errors="replace"` (carried by `UTF8_TEXT`) restores it: a malformed byte costs one character, not the payload, matching the policy #3669 established. `tailnet_serve.py` carries the identical spawn and is fixed in the same commit, because its own docstring says a second, subtly different copy of this spawn is how one comes to be hardened and its sibling not. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: leonlaiyc <276034861+leonlaiyc@users.noreply.github.com>
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the new [DESIGN-REVIEWED] 0c89302 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Only the Windows-half claim ("kills the capture helper thread, leaves What this change shipsInventory (5 items) — 5 justifiedIntent: FIX — tailnet origin derivation stops mis-decoding operator device names (and stops letting malformed bytes escape the
Reuses the repo's existing [FIRST-PRINCIPLES-REVIEWED] 0c89302 |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Problem / Motivation
Goal: The tailnet origin is derived correctly for operators whose Tailscale device names use non-ASCII characters, on every platform.
Both
tailscaleCLI spawns in the dashboard run in text mode with noencoding=, so the child's output is decoded withlocale.getpreferredencoding()— UTF-8 on POSIX, but the legacy ANSI code page on Windows. Device names are operator-chosen free text andtailscale ... --jsonis JSON (UTF-8 by RFC 8259 §8.1), so a device named測試-desksilently decodes to different characters on a cp950 host and_valid_magicdns_namerejects a name that was valid — the tailnet origin is never derived. Bytes that decode under no code page raiseUnicodeDecodeError(aValueError) that escapes theexcept (OSError, subprocess.SubprocessError)guard on POSIX, or kills the capture helper thread on Windows and leavesproc.stdoutasNone.Why it matters
An operator on a Windows host with a non-ASCII device name loses the tailnet origin silently: no error they can see, the feature just does not work. On some byte sequences the gateway leaks a traceback to stderr or mishandles a
Nonestdout instead of the documented "Noneon any failure" contract.Not a goal
UTF8_TEXTmapping used repo-wide.What changed (motivation → approach → change)
text=Truewith noencoding=, deferring to the host code page.**UTF8_TEXT(the repo's existing mapping for children whose encoding is knowable, carryingerrors="replace"), so a malformed byte costs one character rather than the payload.tailnet.pyandtailnet_serve.pycarry the identical spawn and are both fixed. The two files are removed from.github/subprocess-encoding-baseline.txtbecause they no longer rely on the host code page.Backwards compatibility
Compatible: no field, type, or contract is rejected, renamed or removed; the change only fixes how the two spawns decode their own child output.
Tests
test/test_tailnet_e2e.pyadds coverage that the tailscale CLI output is decoded as UTF-8 regardless of the host locale, including a non-ASCII device name and a malformed-byte input that must not escape the failure contract.Manual verification
N/A — unit coverage sufficient; the behavior is deterministic given the mocked CLI output.
Related Issues
Supersedes #9351 (the same fix authored by @leonlaiyc on a fork; opened in-repo so the
.github/baseline edit does not trip the fork workflow-change guard).Pattern harvest
Rule candidate: review-prompt
Pattern: a
subprocess.run(..., text=True)with noencoding=on a child whose output is a known-UTF-8 protocol (JSON) or free text defers to the host code page and mis-decodes on Windows; prefer the repo'sUTF8_TEXTmapping.Checklist