blob: 14c4a0de3cca374dde733d95a3a379d477ef46e2 [file]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
from typing import TYPE_CHECKING, Any
from daemon.driver_utils import (
build_driver_host_warnings,
fetch_driver_hosts,
match_driver_host,
)
from pydap.models import AttachRequestArguments
from shared.protocol.attach import (
COMMAND_NAME,
AttachRequest,
)
from shared.protocol.base import Response
from shared.protocol.driver_list import DriverHostEntry
__all__ = ["COMMAND_NAME", "handle"]
if TYPE_CHECKING:
from daemon.daemon import Daemon
async def _attach_to_matched_driver_host(
daemon: Daemon,
matched_host: DriverHostEntry,
matched_driver: str | None,
*,
weak: bool,
) -> Response[dict[str, Any]]:
"""Attaches zxdb to `matched_host` and builds the driver attach response.
Note:
`matched_driver` is the matched driver URL when attaching via
`--driver`, or the host's first (primary) driver URL when attaching via
`--node` or PID.
"""
extra_fields: dict[str, Any] = {
"process": str(matched_host.host_koid),
}
if weak:
extra_fields["weak"] = True
try:
await daemon.dap_client.attach(
AttachRequestArguments(restart=None, extra_fields=extra_fields)
)
daemon.get_or_create_process(
matched_host.host_koid, name=matched_host.host_name
)
hazard_warning, colocated_warning = build_driver_host_warnings(
matched_host
)
return Response(
success=True,
body={
"driver_host_koid": matched_host.host_koid,
"driver_host_name": matched_host.host_name,
"matched_driver": matched_driver,
"colocated_drivers": matched_host.drivers,
"devices": matched_host.devices,
"attach_mode": "weak" if weak else "strong",
"transport_hazard": matched_host.transport_hazard,
"hazard_warning": hazard_warning,
"colocated_warning": colocated_warning,
"filter_pattern": None,
},
)
except Exception as e:
return Response(
success=False,
message=(
f"Failed to attach to driver_host {matched_host.host_koid}: {e}"
),
)
async def _install_driver_attach_filter(
daemon: Daemon, req: AttachRequest
) -> Response[dict[str, Any]]:
"""Installs a deferred process filter in zxdb when `--wait` is requested."""
filter_pattern = "driver_host"
extra_fields: dict[str, Any] = {"process": filter_pattern}
if req.weak:
extra_fields["weak"] = True
if req.recursive:
extra_fields["recursive"] = True
if req.job_only:
extra_fields["job_only"] = True
requested_target = req.driver or req.node
filter_warning = (
f"zxdb cannot match driver or device node '{requested_target}' "
f"directly to a driver_host process; installed filter '{filter_pattern}' "
"will attach to every newly started driver_host. Recommend using --weak "
"to avoid pausing threads unexpectedly."
)
try:
await daemon.dap_client.attach(
AttachRequestArguments(restart=None, extra_fields=extra_fields)
)
return Response(
success=True,
body={
"driver_host_koid": None,
"driver_host_name": None,
"matched_driver": None,
"colocated_drivers": [],
"devices": [],
"attach_mode": "filter",
"transport_hazard": False,
"hazard_warning": None,
"colocated_warning": None,
"filter_pattern": filter_pattern,
"requested_target": requested_target,
"filter_warning": filter_warning,
},
)
except Exception as e:
return Response(
success=False,
message=(
f"Failed to install attach filter '{filter_pattern}': {e}"
),
)
async def _handle_driver_or_node_attach(
daemon: Daemon, req: AttachRequest
) -> Response[dict[str, Any]]:
"""Resolves a `--driver` or `--node` attach request via `ffx driver`."""
if req.exact:
return Response(
success=False,
message="--exact cannot be used with --driver or --node",
)
hosts: list[DriverHostEntry] = []
ffx_error: str | None = None
try:
hosts = await fetch_driver_hosts(daemon)
except Exception as e:
ffx_error = str(e)
matched_host, matched_driver = match_driver_host(
hosts, driver=req.driver, node=req.node
)
if matched_host is not None:
return await _attach_to_matched_driver_host(
daemon, matched_host, matched_driver, weak=req.weak
)
if req.wait:
return await _install_driver_attach_filter(daemon, req)
target_desc = req.driver or req.node or ""
if ffx_error is not None:
# The lookup itself failed, so "no match" would be misleading, and
# suggesting --wait would point at a filter that matches every new
# driver host.
return Response(
success=False,
message=(
f"Could not look up the driver host for '{target_desc}':"
f" {ffx_error}. To attach without `ffx driver`, find the"
" driver host process name (for example"
" 'driver-host-#<colocation name>') with"
" `fx debug cli console ps`, then run"
" `fx debug cli attach --exact --weak '<name>'`."
" The transport hazard warning needs `ffx driver`, so it is"
" not shown on that path; avoid the host that carries the"
" device connection."
),
)
return Response(
success=False,
message=(
f"No running driver_host matched '{target_desc}'. "
"Use --wait to install a filter for future driver starts."
),
)
async def handle(daemon: Daemon, req: AttachRequest) -> Response[Any]:
"""Handles an `attach` request by forwarding zxdb attach filters via DAP."""
if not daemon.zxdb_writer:
return Response(
success=False, message="Not connected to zxdb DAP server"
)
if req.driver is not None or req.node is not None:
return await _handle_driver_or_node_attach(daemon, req)
# AttachRequestArguments is a generic DAP model. Zxdb-specific arguments
# (like "process", "weak", "exact", "recursive", "job_only") must be passed
# via extra_fields, which are flattened during serialization.
extra_fields: dict[str, Any] = {"process": req.filter}
if req.weak:
extra_fields["weak"] = True
if req.exact:
extra_fields["exact"] = True
if req.recursive:
extra_fields["recursive"] = True
if req.job_only:
extra_fields["job_only"] = True
attach_args = AttachRequestArguments(
restart=None, extra_fields=extra_fields
)
try:
resp = await daemon.dap_client.attach(attach_args)
return Response(success=True, body=resp.dump_dap())
except Exception as e:
return Response(success=False, message=f"Failed to attach: {e}")