Skip to content

refactor(platform): phase 6 migrate daemon IPC lifecycle #1334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zackees merged 3 commits into from
Aug 21, 2026
Merged

refactor(platform): phase 6 migrate daemon IPC lifecycle #1334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
404a24d
refactor(platform): migrate daemon IPC lifecycle
zackees Aug 21, 2026
722ad4c
fix(platform): enforce owner-only macOS local endpoints post-bind
zackees Aug 21, 2026
ef36a1e
chore(ci): regenerate platform boundary inventory after macOS IPC fix
zackees Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 5 additions & 2 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,9 +132,12 @@ bincode = "1"
# to the version running-process 4.3.0 re-exports so the wire types stay
# compatible. See crates/fbuild-daemon/src/broker.
prost = "0.14"
# fbuild-daemon binds the running-process backend endpoint directly so the
# broker can verify and route to versioned daemon processes.
# fbuild-core's selected IPC implementations bind the private running-process
# backend endpoint and construct the daemon TCP listener.
interprocess = "2.4.2"
socket2 = "0.6"
# Windows owner-only endpoint descriptors use static UTF-16 SDDL.
widestring = "1.2"
rayon = "1"
tracing-test = "0.2"
# Terminal coloring for `fbuild build --shrink` reporting (FastLED/fbuild#493).
Expand Down
22 changes: 14 additions & 8 deletions ci/enforce_platform_boundary.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,18 @@
),
}
)
AUTHORIZED_BOUNDARY_FINDINGS.update(
{
(
"crates/fbuild-core/\x43argo.toml",
"native_dependency",
dependency,
"ipc",
"host_mechanic",
)
for dependency in ("interprocess", "socket2")
}
)
LEDGER_KINDS = {
"attr_cfg",
"cfg_macro",
Expand All @@ -81,14 +93,8 @@
# Pre-expansion rustc visits exactly one of these mutually exclusive cfg
# bodies on any host, while the whole-tree scanner intentionally inventories
# both. Keep this projection adjustment explicit and occurrence-specific.
DYLINT_HOST_EXCLUSIVE_ADJUSTMENTS = collections.Counter(
{
(
"crates/fbuild-daemon/src/broker/backend.rs",
"native_import",
"interprocess",
): 1,
}
DYLINT_HOST_EXCLUSIVE_ADJUSTMENTS: collections.Counter[tuple[str, str, str]] = (
collections.Counter()
)


Expand Down
13 changes: 0 additions & 13 deletions ci/platform_boundary_ledger.tsv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,22 +19,9 @@ crates/fbuild-cli/src/cli/usb_recovery.rs native_path windows_sys:: 2 process ho
crates/fbuild-cli/src/cli/usb_recovery.rs native_path windows_sys:: 3 process host_mechanic
crates/fbuild-config/src/bin/enrich_boards.rs attr_cfg #[cfg(not(windows))] 0 host host_mechanic
crates/fbuild-config/src/bin/enrich_boards.rs attr_cfg #[cfg(windows)] 0 host host_mechanic
crates/fbuild-daemon/Cargo.toml native_dependency interprocess 0 process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs attr_cfg #[cfg(unix)] 0 ipc host_mechanic
crates/fbuild-daemon/src/broker/backend.rs attr_cfg #[cfg(windows)] 0 ipc host_mechanic
crates/fbuild-daemon/src/broker/backend.rs native_path interprocess::local_socket 0 process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs native_path interprocess::local_socket 1 process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs native_path interprocess::local_socket 2 process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs native_path interprocess::local_socket 3 process host_mechanic
crates/fbuild-daemon/src/handlers/emulator/tests_npm_cache.rs attr_cfg #[cfg(windows)] 0 host_executable host_artifact_policy
crates/fbuild-daemon/src/handlers/emulator/tests_process.rs attr_cfg #[cfg(not(windows))] 0 host_executable host_artifact_policy
crates/fbuild-daemon/src/handlers/emulator/tests_process.rs attr_cfg #[cfg(windows)] 0 host_executable host_artifact_policy
crates/fbuild-daemon/src/main.rs attr_cfg #[cfg(not(windows))] 0 host host_mechanic
crates/fbuild-daemon/src/main.rs attr_cfg #[cfg(windows)] 0 host host_mechanic
crates/fbuild-daemon/src/main.rs attr_cfg #[cfg(windows)] 1 host host_mechanic
crates/fbuild-daemon/src/main.rs attr_cfg #[cfg(windows)] 2 host host_mechanic
crates/fbuild-daemon/src/main.rs attr_cfg #[cfg(windows)] 3 host host_mechanic
crates/fbuild-daemon/src/main.rs native_path std::os::windows::io::AsRawSocket 0 process host_mechanic
crates/fbuild-deploy/src/lpc.rs attr_cfg #[cfg(not(target_os=))] 0 device host_mechanic
crates/fbuild-deploy/src/lpc.rs attr_cfg #[cfg(not(windows))] 0 device host_mechanic
crates/fbuild-deploy/src/lpc.rs attr_cfg #[cfg(target_os=)] 0 device host_mechanic
Expand Down
9 changes: 7 additions & 2 deletions ci/platform_boundary_research.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"mach2",
"nix",
"portable_pty",
"socket2",
"winapi",
"windows",
"windows_sys",
Expand All @@ -51,15 +52,15 @@
r"\bstd\s*::\s*os\s*::\s*(?:windows|unix|linux|macos)\b"
r"(?:\s*::\s*[A-Za-z_][A-Za-z0-9_]*)*"
),
re.compile(r"\b(?:windows_sys|winapi|libc|mach2|nix|portable_pty)\s*::"),
re.compile(r"\b(?:windows_sys|winapi|libc|mach2|nix|portable_pty|socket2)\s*::"),
re.compile(r"\bwindows\s*::\s*Win32\b"),
re.compile(r"\binterprocess\s*::\s*os\s*::\s*(?:windows|unix)\b"),
re.compile(r"\binterprocess\s*::\s*local_socket\b"),
re.compile(r"\btokio\s*::\s*net\s*::\s*(?:windows|UnixListener|UnixStream)\b"),
re.compile(r"\bwindows\s*::"),
)
SINGLE_NATIVE_USE = re.compile(
r"\buse\s+(interprocess|libc|mach2|nix|portable_pty|winapi|windows|windows_sys)"
r"\buse\s+(interprocess|libc|mach2|nix|portable_pty|socket2|winapi|windows|windows_sys)"
r"\s*(?:as\s+[A-Za-z_][A-Za-z0-9_]*\s*)?;"
)
COMPILE_HOST_CONST = re.compile(r"\bstd\s*::\s*env\s*::\s*consts\s*::\s*(?:OS|ARCH)\b")
Expand Down Expand Up @@ -210,6 +211,8 @@ def enclosing_function(text: str, offset: int) -> str:

def classify(path: str, kind: str, normalized: str = "", context: str = "") -> tuple[str, str]:
"""Assign the phase-1 owner class; phase 2 validates this per occurrence."""
if path.startswith("crates/fbuild-core/src/platform/") and path.endswith("/ipc.rs"):
return "ipc", "host_mechanic"
if path == "crates/fbuild-core/\x43argo.toml":
unix_table = "[target.'cfg(unix)'.dependencies]"
windows_table = "[target.'cfg(windows)'.dependencies]"
Expand All @@ -220,6 +223,8 @@ def classify(path: str, kind: str, normalized: str = "", context: str = "") -> t
("windows-sys", windows_table),
}:
return "fs", "host_mechanic"
if kind == "native_dependency" and normalized in {"interprocess", "socket2"}:
return "ipc", "host_mechanic"
if kind in {"native_import", "native_path", "native_dependency"}:
if normalized == "std::env::current_exe":
return "host_executable", "host_mechanic"
Expand Down
45 changes: 25 additions & 20 deletions ci/platform_boundary_research.tsv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,26 +19,38 @@ crates/fbuild-cli/src/cli/usb_recovery.rs 259 native_path windows_sys:: process
crates/fbuild-cli/src/cli/usb_recovery.rs 262 native_path std::os::windows::ffi::OsStrExt process host_mechanic
crates/fbuild-config/src/bin/enrich_boards.rs 74 attr_cfg #[cfg(windows)] host host_mechanic
crates/fbuild-config/src/bin/enrich_boards.rs 78 attr_cfg #[cfg(not(windows))] host host_mechanic
crates/fbuild-core/Cargo.toml 46 target_dependency_table [target.'cfg(unix)'.dependencies] fs host_mechanic
crates/fbuild-core/Cargo.toml 48 native_dependency libc fs host_mechanic
crates/fbuild-core/Cargo.toml 50 target_dependency_table [target.'cfg(windows)'.dependencies] fs host_mechanic
crates/fbuild-core/Cargo.toml 53 native_dependency windows-sys fs host_mechanic
crates/fbuild-core/Cargo.toml 47 native_dependency interprocess ipc host_mechanic
crates/fbuild-core/Cargo.toml 48 native_dependency socket2 ipc host_mechanic
crates/fbuild-core/Cargo.toml 50 target_dependency_table [target.'cfg(unix)'.dependencies] fs host_mechanic
crates/fbuild-core/Cargo.toml 52 native_dependency libc fs host_mechanic
crates/fbuild-core/Cargo.toml 54 target_dependency_table [target.'cfg(windows)'.dependencies] fs host_mechanic
crates/fbuild-core/Cargo.toml 57 native_dependency windows-sys fs host_mechanic
crates/fbuild-core/src/platform/executable.rs 56 native_path std::env::current_exe host_executable host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 2 native_path std::os::unix::fs::PermissionsExt fs host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 40 native_path std::os::unix::fs::symlink fs host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 84 native_path std::os::unix::ffi::OsStrExt process host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 89 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 91 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/linux/fs.rs 101 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/linux/mod.rs 9 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/linux/ipc.rs 1 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/linux/ipc.rs 2 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/linux/ipc.rs 3 native_path interprocess::os::unix ipc host_mechanic
crates/fbuild-core/src/platform/linux/ipc.rs 4 native_path socket2:: ipc host_mechanic
crates/fbuild-core/src/platform/linux/ipc.rs 66 native_path std::os::unix::fs::PermissionsExt ipc host_mechanic
crates/fbuild-core/src/platform/linux/mod.rs 10 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/linux/process.rs 1 native_path std::os::unix::process::ExitStatusExt process host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 2 native_path std::os::unix::fs::PermissionsExt fs host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 40 native_path std::os::unix::fs::symlink fs host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 84 native_path std::os::unix::ffi::OsStrExt process host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 89 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 91 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/macos/fs.rs 101 native_path libc:: process host_mechanic
crates/fbuild-core/src/platform/macos/mod.rs 9 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/macos/ipc.rs 1 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/macos/ipc.rs 2 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/macos/ipc.rs 3 native_path socket2:: ipc host_mechanic
crates/fbuild-core/src/platform/macos/ipc.rs 19 native_path std::os::unix::fs::PermissionsExt ipc host_mechanic
crates/fbuild-core/src/platform/macos/ipc.rs 72 native_path std::os::unix::fs::PermissionsExt ipc host_mechanic
crates/fbuild-core/src/platform/macos/mod.rs 10 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/macos/process.rs 1 native_path std::os::unix::process::ExitStatusExt process host_mechanic
crates/fbuild-core/src/platform/windows/fs.rs 2 native_path std::os::windows::ffi::OsStrExt process host_mechanic
crates/fbuild-core/src/platform/windows/fs.rs 3 native_path std::os::windows::fs fs host_mechanic
Expand All @@ -47,24 +59,17 @@ crates/fbuild-core/src/platform/windows/fs.rs 50 native_path std::os::windows::f
crates/fbuild-core/src/platform/windows/fs.rs 78 native_path windows_sys:: process host_mechanic
crates/fbuild-core/src/platform/windows/fs.rs 133 native_path windows_sys:: process host_mechanic
crates/fbuild-core/src/platform/windows/fs.rs 177 native_path windows_sys:: process host_mechanic
crates/fbuild-core/src/platform/windows/mod.rs 9 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 1 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 2 native_path interprocess::local_socket ipc host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 3 native_path interprocess::os::windows ipc host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 4 native_path interprocess::os::windows ipc host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 5 native_path socket2:: ipc host_mechanic
crates/fbuild-core/src/platform/windows/ipc.rs 6 native_path std::os::windows::io::AsRawSocket ipc host_mechanic
crates/fbuild-core/src/platform/windows/mod.rs 10 compile_host_fact std::env::consts::ARCH host host_mechanic
crates/fbuild-core/src/platform/windows/process.rs 1 native_path std::os::windows::io::AsHandle process host_mechanic
crates/fbuild-daemon/Cargo.toml 58 native_dependency interprocess process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 11 native_path interprocess::local_socket process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 188 native_path interprocess::local_socket process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 189 attr_cfg #[cfg(unix)] ipc host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 195 native_path interprocess::local_socket process host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 200 attr_cfg #[cfg(windows)] ipc host_mechanic
crates/fbuild-daemon/src/broker/backend.rs 202 native_path interprocess::local_socket process host_mechanic
crates/fbuild-daemon/src/handlers/emulator/tests_npm_cache.rs 146 attr_cfg #[cfg(windows)] host_executable host_artifact_policy
crates/fbuild-daemon/src/handlers/emulator/tests_process.rs 9 attr_cfg #[cfg(windows)] host_executable host_artifact_policy
crates/fbuild-daemon/src/handlers/emulator/tests_process.rs 21 attr_cfg #[cfg(not(windows))] host_executable host_artifact_policy
crates/fbuild-daemon/src/main.rs 319 attr_cfg #[cfg(windows)] host host_mechanic
crates/fbuild-daemon/src/main.rs 646 attr_cfg #[cfg(windows)] host host_mechanic
crates/fbuild-daemon/src/main.rs 652 attr_cfg #[cfg(not(windows))] host host_mechanic
crates/fbuild-daemon/src/main.rs 729 attr_cfg #[cfg(windows)] host host_mechanic
crates/fbuild-daemon/src/main.rs 731 native_path std::os::windows::io::AsRawSocket process host_mechanic
crates/fbuild-daemon/src/main.rs 776 attr_cfg #[cfg(windows)] host host_mechanic
crates/fbuild-deploy/src/lpc.rs 27 attr_cfg #[cfg(target_os=)] device host_mechanic
crates/fbuild-deploy/src/lpc.rs 31 attr_cfg #[cfg(not(target_os=))] device host_mechanic
crates/fbuild-deploy/src/lpc.rs 972 attr_cfg #[cfg(windows)] device host_mechanic
Expand Down
19 changes: 18 additions & 1 deletion ci/test_enforce_platform_boundary.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ def setUpClass(cls) -> None:
cls.observed = boundary.rows_from_findings(boundary.research.inventory())

def test_committed_exact_occurrence_ledger_matches_whole_tree(self) -> None:
self.assertEqual(len(self.expected), 107)
self.assertEqual(len(self.expected), 94)
self.assertFalse(boundary.validate_ledger(self.expected))
self.assertFalse(boundary.compare(self.expected, self.observed))

Expand Down Expand Up @@ -105,6 +105,23 @@ def test_rp2040_filesystem_mechanics_use_the_neutral_facade(self) -> None:
for forbidden in ("AsRawHandle", "CancelSynchronousIo", ".raw_os_error()"):
self.assertNotIn(forbidden, source)

def test_daemon_ipc_and_shutdown_use_neutral_facades(self) -> None:
backend = (
boundary.ROOT / "crates/fbuild-daemon/src/broker/backend.rs"
).read_text(encoding="utf-8")
main = (boundary.ROOT / "crates/fbuild-daemon/src/main.rs").read_text(
encoding="utf-8"
)

self.assertNotIn("interprocess", backend)
for forbidden in (
"socket2",
"AsRawSocket",
"SetConsoleCtrlHandler",
"windows_console",
):
self.assertNotIn(forbidden, main)

def test_executable_spelling_does_not_bypass_the_executable_facade(self) -> None:
host_selected_exe = re.compile(
r"if\s+(?:fbuild_core|crate)::platform::host::is_windows\(\)"
Expand Down
22 changes: 22 additions & 0 deletions ci/test_platform_boundary_research.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,28 @@ def test_core_native_dependency_ownership_requires_matching_target_table(self) -
[("process", "host_mechanic"), ("fs", "host_mechanic")],
)

def test_core_ipc_dependencies_have_exact_ownership(self) -> None:
path = "crates/fbuild-core/\x43argo.toml"
for dependency in ("interprocess", "socket2"):
with self.subTest(dependency=dependency):
self.assertEqual(
platform_boundary_research.classify(
path, "native_dependency", dependency, ""
),
("ipc", "host_mechanic"),
)

def test_selected_ipc_implementation_has_exact_ownership(self) -> None:
self.assertEqual(
platform_boundary_research.classify(
"crates/fbuild-core/src/platform/windows/ipc.rs",
"native_path",
"socket2::",
"",
),
("ipc", "host_mechanic"),
)

def test_mixed_qemu_permissions_are_migrated_but_context_stays_classified(self) -> None:
path = platform_boundary_research.ROOT / "crates/fbuild-toolchain/src/toolchain/esp_qemu.rs"
findings = platform_boundary_research.scan_rust(path, platform_boundary_research.ROOT)
Expand Down
6 changes: 6 additions & 0 deletions crates/fbuild-core/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ fs2 = { workspace = true }
# Stable cross-platform file identity handles; construction remains confined
# to the selected filesystem implementation.
same-file = { workspace = true }
# Local endpoint transport and native TCP listener construction are confined
# to the selected `platform::ipc` implementations.
interprocess = { workspace = true }
socket2 = { workspace = true }

[target.'cfg(unix)'.dependencies]
# Selected Unix filesystem mechanics query the exact mount containing a path.
Expand All @@ -51,6 +55,8 @@ libc = { workspace = true }
# Selected Windows filesystem mechanics: removable-volume facts and retiring
# a kernel-blocked output handle after its watchdog expires.
windows-sys = { version = "0.52", features = ["Win32_Foundation", "Win32_Storage_FileSystem", "Win32_System_IO"] }
# Selected Windows IPC creates a protected owner-only pipe descriptor.
widestring = { workspace = true }

[dev-dependencies]
tempfile = { workspace = true }
Expand Down
6 changes: 6 additions & 0 deletions crates/fbuild-core/src/platform/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,9 @@ link/reparse classification, volume facts, native error classification, shared
destination opening, atomic replacement, and blocked-I/O retirement. Cache
sizing, archive traversal, authorization, locking, diagnostics, and retry policy
remain with their product owners.

`ipc` owns fbuild local-endpoint bind/connect/accept and peer facts, owner-only
Unix endpoint creation, TCP listener socket policy, and endpoint readiness
probing. Broker framing/routing, daemon retry/yield policy, and HTTP/protobuf
compatibility remain with the daemon. Additional native shutdown notifications
route through `process` into the daemon's neutral shutdown channel.
Loading
Loading