blob: 3fba4310953ce3225b0f65db16bd3f2f71fc79f2 [file]
# Copyright 2025 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.
import asyncio
import hashlib
import json
import os
import shlex
from contextlib import asynccontextmanager
from typing import AsyncGenerator, Callable, Literal, Protocol
import build_dir
from async_utils.command import AsyncCommand, AsyncCommandError, CommandOutput
from ffx_cmd import FfxCmd
from fx_cmd import FxCmd
_DEFAULT_SERVER_STARTUP_TIMEOUT = 30
_CHECK_SERVER_POLLING_INTERVAL = 0.2
_DEFAULT_PROBE_TIMEOUT = 15.0
_DEFAULT_DEREGISTER_TIMEOUT = 5.0
_DEFAULT_SERVER_STOP_TIMEOUT = 10.0
_DEFAULT_ABORT_GRACE_PERIOD = 5.0
class CommandRunner(Protocol):
"""Callable that executes an `fx` subcommand asynchronously.
Args:
*args (str): Subcommand and arguments to pass to `fx`.
timeout (float | None): Optional timeout in seconds before terminating
the command.
abort_signal (asyncio.Event | None): Optional event that, when set,
requests graceful termination of the running command.
quiet_mode (bool): Whether to suppress command lifecycle output in
interactive status displays.
Returns:
CommandOutput | None: Completed command output, or None if the command
could not be started.
"""
async def __call__(
self,
*args: str,
timeout: float | None = None,
abort_signal: asyncio.Event | None = None,
quiet_mode: bool = False,
) -> CommandOutput | None:
...
def _default_command_runner(
build_directory: str | os.PathLike[str] | None = None,
) -> CommandRunner:
"""Creates a `CommandRunner` backed by `FxCmd` and `AsyncCommand`."""
resolved_build_dir = (
os.fspath(build_directory) if build_directory is not None else None
)
async def run_fx(
*args: str,
timeout: float | None = None,
abort_signal: asyncio.Event | None = None,
quiet_mode: bool = False,
) -> CommandOutput | None:
del quiet_mode
started: AsyncCommand | None = None
abort_task: asyncio.Task[None] | None = None
try:
fx_cmd = FxCmd(
build_directory=resolved_build_dir,
timeout=timeout,
)
started = await fx_cmd.start(*args)
if abort_signal is not None:
async def handle_abort() -> None:
await abort_signal.wait()
started.terminate()
await asyncio.sleep(_DEFAULT_ABORT_GRACE_PERIOD)
started.kill()
abort_task = asyncio.create_task(handle_abort())
return await started.run_to_completion()
except asyncio.CancelledError:
if started is not None:
started.kill()
raise
except AsyncCommandError:
return None
finally:
if abort_task is not None:
abort_task.cancel()
return run_fx
class PackageServingException(Exception):
"""This exception is raised on unsuccessful package serving attempts."""
class PackageServingCLIException(SystemExit, PackageServingException):
"""
Like `PackageServingException`, but does not print a stack trace when uncaught.
Used in the `run_and_stop_on_exit()` asynccontextmanager function, where concise error messages
are more helpful than noisy stack traces for CLI developer tools.
"""
async def is_running(
*,
timeout: float | None = None,
run_command: CommandRunner | None = None,
) -> bool:
"""
Checks whether a package server is currently running.
Args:
timeout (float | None): Subprocess timeout in seconds.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
Returns:
bool: Whether a package server is currently running.
"""
runner = run_command or _default_command_runner()
result = await runner("is-package-server-running", timeout=timeout)
return result is not None and result.return_code == 0
def is_fuchsia_repo_registered(
output: str, repo_name: str | None = None
) -> bool:
"""
Checks whether a `fuchsia.com` repository is present in `ffx` JSON output.
Args:
output (str): JSON stdout from `ffx --machine json target repository list`.
repo_name (str | None): Optional repository name to require when
matching `fuchsia.com` registrations.
Returns:
bool: True if a matching `fuchsia.com` repository entry is present.
Raises:
json.JSONDecodeError: If `output` is not valid JSON.
"""
parsed = json.loads(output)
# Expected format from ffx --machine json: {"ok": {"data": [...]}}
entries = []
if isinstance(parsed, dict) and "ok" in parsed:
data = parsed["ok"].get("data", [])
if isinstance(data, list):
entries = data
elif isinstance(parsed, list):
entries = parsed
for entry in entries:
if isinstance(entry, dict):
name = entry.get("name", "").removeprefix("fuchsia-pkg://")
if repo_name is not None and name != repo_name:
continue
aliases = entry.get("aliases", [])
if name == "fuchsia.com" or "fuchsia.com" in aliases:
return True
return False
async def is_fuchsia_repo_registered_on_device(
*,
repo_name: str | None = None,
timeout: float = _DEFAULT_PROBE_TIMEOUT,
run_command: CommandRunner | None = None,
) -> bool:
"""
Checks whether a `fuchsia.com` repository is registered on the target device.
Args:
repo_name (str | None): Optional repository name to require when
matching `fuchsia.com` registrations.
timeout (float): Subprocess timeout in seconds.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
Returns:
bool: True if a matching `fuchsia.com` repository is registered on the
target device.
"""
runner = run_command or _default_command_runner()
repo_output = await runner(
"ffx",
"--machine",
"json",
"target",
"repository",
"list",
timeout=timeout,
quiet_mode=True,
)
if repo_output is None or repo_output.return_code != 0:
return False
try:
return is_fuchsia_repo_registered(
repo_output.stdout, repo_name=repo_name
)
except json.JSONDecodeError:
return False
async def is_connected_to_device(
*,
repo_name: str | None = None,
timeout: float = _DEFAULT_PROBE_TIMEOUT,
run_command: CommandRunner | None = None,
) -> bool:
"""
Checks whether a package server is running and registered on the target device.
Args:
repo_name (str | None): Optional repository name to require when
matching `fuchsia.com` registrations on the target.
timeout (float): Subprocess timeout in seconds.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
Returns:
bool: True only if a host package server is running and registered on
the target device.
"""
if not await is_running(
timeout=timeout,
run_command=run_command,
):
return False
return await is_fuchsia_repo_registered_on_device(
repo_name=repo_name,
timeout=timeout,
run_command=run_command,
)
async def wait_for_registration(
*,
repo_name: str | None = None,
retries: int = 30,
interval: float = 1.0,
timeout: float = _DEFAULT_PROBE_TIMEOUT,
run_command: CommandRunner | None = None,
) -> bool:
"""
Polls until a `fuchsia.com` repository is registered on the target device.
Args:
repo_name (str | None): Optional repository name to require when
matching `fuchsia.com` registrations. Filtering by an expected
ephemeral repository name prevents unrelated stale registrations
from causing the wait to return early.
retries (int): Maximum number of polling attempts.
interval (float): Delay in seconds between polling attempts.
timeout (float): Per-probe subprocess timeout in seconds.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
Returns:
bool: True if the repository is registered within `retries` attempts.
"""
runner = run_command or _default_command_runner()
for _ in range(retries):
if await is_fuchsia_repo_registered_on_device(
repo_name=repo_name,
timeout=timeout,
run_command=runner,
):
return True
await asyncio.sleep(interval)
return False
async def deregister(
name: str,
*,
timeout: float = _DEFAULT_DEREGISTER_TIMEOUT,
run_command: CommandRunner | None = None,
) -> CommandOutput | None:
"""
Deregisters a package repository from the target device.
Args:
name (str): Repository name to deregister from the target.
timeout (float): Subprocess timeout in seconds.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
Returns:
CommandOutput | None: Subprocess output, or None if execution failed.
"""
runner = run_command or _default_command_runner()
return await runner(
"ffx",
"target",
"repository",
"deregister",
"-r",
name,
timeout=timeout,
quiet_mode=True,
)
async def serve(
*,
name: str | None = None,
prefix: str = "tmp",
build_directory: str | os.PathLike[str] | None = None,
run_command: CommandRunner | None = None,
on_warning: Callable[[str], None] | None = None,
) -> tuple[asyncio.Task[None], asyncio.Event]:
"""
Starts a managed background package server and returns its control handles.
Deregisters any stale target registration for the repository name before
starting the server, and when the returned event is set, deregisters the
repository from the target before terminating the server process group.
Args:
name (str | None): Explicit repository name, or None to derive a
deterministic ephemeral name using `prefix` and `build_directory`.
prefix (str): Tool-specific prefix when deriving an ephemeral repository
name.
build_directory (str | PathLike[str] | None): Build directory whose
package repository is being served, or None for the active build
directory.
run_command (CommandRunner | None): Optional runner for `fx`
subcommands.
on_warning (Callable[[str], None] | None): Optional callback invoked
with a human-readable warning message if teardown deregistration or
server shutdown fails.
Returns:
tuple[Task[None], Event]: Background lifecycle task and the event that
triggers graceful deregistration and server shutdown when set.
Raises:
build_dir.GetBuildDirectoryError: If `build_directory` is None (when
deriving `name` or using the default command runner) and no active
build directory can be determined.
"""
cancel_event = asyncio.Event()
repo_name = name or ephemeral_repository_name(prefix, build_directory)
runner = run_command or _default_command_runner(
build_directory=build_directory
)
# Deregister any stale registration left on the device by an interrupted
# prior run so `wait_for_registration` waits for the newly started server
# instance to register its port.
await deregister(repo_name, run_command=runner)
started_event = asyncio.Event()
repo_deregistered_event = asyncio.Event()
# Aborting the `fx serve` task stops the repository server but does not
# remove the corresponding repository config or rewrite rule from the
# device. The repository config is explicitly deregistered from the device
# (which also removes the rewrite rule) before cancelling the server task to
# avoid the pkg-resolver's AutoClient logging that the server has gone away.
async def impl() -> None:
serve_task: asyncio.Task[CommandOutput | None] | None = None
try:
serve_task = asyncio.create_task(
runner(
"serve",
"-l",
"0",
"--name",
repo_name,
abort_signal=repo_deregistered_event,
quiet_mode=True,
)
)
started_event.set()
await cancel_event.wait()
finally:
try:
deregister_output = await deregister(
repo_name,
run_command=runner,
)
if (
deregister_output is None
or deregister_output.return_code != 0
):
raise RuntimeError(
f"exit code {deregister_output.return_code if deregister_output is not None else -1}"
)
except Exception as e:
if on_warning is not None:
on_warning(
f"Failed to deregister temporary package repository {repo_name}: {e}"
)
finally:
repo_deregistered_event.set()
if serve_task is not None:
try:
await asyncio.wait_for(
serve_task, timeout=_DEFAULT_SERVER_STOP_TIMEOUT
)
except TimeoutError:
if on_warning is not None:
on_warning(
f"Timed out waiting for temporary package server ({repo_name}) to stop."
)
serve_task.cancel()
task = asyncio.create_task(impl())
try:
await started_event.wait()
except BaseException:
task.cancel()
try:
await task
except asyncio.CancelledError:
pass
raise
return (task, cancel_event)
async def wait_for_package_server(
process: asyncio.subprocess.Process, timeout: float, interval: float
) -> bool:
"""
Waits for a package server to come online by periodically polling.
Exits early if the given package serving process terminates.
Args:
process (Process): The package serving process. If it terminates early, this function
automatically returns False.
timeout (float): The maximum amount of time (in seconds) to wait for the package server.
interval (float): The delay (in seconds) between each package server availability check.
Returns:
bool: Whether the package serving process is available within `timeout` seconds.
"""
async def poll_is_running(interval: float) -> Literal[True]:
while not await is_running():
await asyncio.sleep(interval)
return True
async def wait_for_process(
process: asyncio.subprocess.Process,
) -> Literal[False]:
await process.wait()
return False
async def wait_for_timeout(timeout: float) -> Literal[False]:
await asyncio.sleep(timeout)
return False
# This task represents the True condition: When `fx is-package-server-running` is True.
poll_task = asyncio.create_task(poll_is_running(interval))
# This task represents a False condition: When `process` terminates unexpectedly.
process_task = asyncio.create_task(wait_for_process(process))
# This task represents a False condition: When `timeout` has been reached.
timeout_task = asyncio.create_task(wait_for_timeout(timeout))
# Race the three tasks, we use the value of whichever task completes first.
all_tasks = [poll_task, process_task, timeout_task]
finished_task, _ = await asyncio.wait(
all_tasks,
return_when=asyncio.FIRST_COMPLETED,
)
is_serving = finished_task.pop().result() if finished_task else False
# Cleanup other tasks.
for task in all_tasks:
task.cancel()
try:
await task
except asyncio.CancelledError:
pass
return is_serving
def is_package_repository_built() -> bool:
"""
Checks whether the in-tree package repository is built.
Returns:
bool: Whether the in-tree package repository is built.
"""
return (
build_dir.get_build_directory()
/ "amber-files"
/ "repository"
/ "9.root.json"
).is_file()
def ephemeral_repository_name(
prefix: str = "tmp",
build_directory: str | os.PathLike[str] | None = None,
) -> str:
"""
Returns deterministic ephemeral repository name for a build directory.
Args:
prefix (str): Tool-specific prefix for the repository name.
build_directory (str | PathLike[str] | None): Build directory whose
package repository is being served, or None to use the active build
directory.
Returns:
str: Deterministic repository name prefixed with `<prefix>-`.
Raises:
build_dir.GetBuildDirectoryError: If `build_directory` is None and no
active build directory can be determined.
"""
out_dir = (
build_directory
if build_directory is not None
else build_dir.get_build_directory()
)
repo_path = os.path.realpath(os.path.join(out_dir, "amber-files"))
path_hash = hashlib.sha256(repo_path.encode("utf-8")).hexdigest()[:16]
return f"{prefix}-{path_hash}"
async def get_arguments(name: str | None = None) -> tuple[str, ...]:
"""
Gets the ffx command line arguments for starting a package server.
Args:
name (str | None): Optionally specify the main repository name for this server.
Returns:
tuple[str, ...]: A tuple of ffx arguments for package serving.
"""
out_dir = build_dir.get_build_directory()
repo_name = name or ephemeral_repository_name(build_directory=out_dir)
ffx_default_port = await FfxCmd().start(
"config",
"get",
"repository.server.default_port",
)
stdout = (await ffx_default_port.run_to_completion()).stdout
try:
port = int(stdout.strip(' \t\n\r"'))
except ValueError:
port = 8083
# LINT.IfChange
return (
"repository",
"server",
"start",
"--foreground",
"--address",
f"[::]:{port}",
"--repository",
repo_name,
"--repo-path",
str(out_dir / "amber-files"),
"--trusted-root",
str(out_dir / "amber-files" / "repository" / "9.root.json"),
"--alias",
"fuchsia.com",
"--alias",
"chromium.org",
)
# LINT.ThenChange(//tools/devshell/serve)
async def start(
name: str | None = None, timeout: float = _DEFAULT_SERVER_STARTUP_TIMEOUT
) -> asyncio.subprocess.Process:
"""
Starts a package server.
Args:
name (str | None): Optionally specify the main repository name for this server.
timeout (float): The maximum amount of time (in seconds) to wait for the package server.
Returns:
Process: An asyncio Process instance for the package server.
"""
if not is_package_repository_built():
raise PackageServingException("The package repository is not built!")
repo_name = name or ephemeral_repository_name()
fx = FxCmd()
ffx = FfxCmd()
args = await get_arguments(repo_name)
process = await asyncio.create_subprocess_exec(
*fx.command_line(*ffx.command_line(*args)),
stdout=asyncio.subprocess.DEVNULL,
stderr=asyncio.subprocess.DEVNULL,
)
if await wait_for_package_server(
process, timeout, _CHECK_SERVER_POLLING_INTERVAL
):
return process
errmsg: str
if process.returncode is None:
errmsg = f"The package server didn't start within {timeout}s."
process.terminate()
await process.wait()
await stop(repo_name)
else:
errmsg = f"The package server exited with code {process.returncode}."
raise PackageServingException(errmsg + f"\nCommand: {shlex.join(args)}")
async def stop(name: str | None = None) -> None:
"""
Stops running package servers.
Args:
name (str | None): Optionally specify the repository name of the server to terminate.
If omitted, all package servers will be stopped.
"""
process = await FfxCmd().start(
"repository",
"server",
"stop",
*([name] if name else []),
)
await process.run_to_completion()
@asynccontextmanager
async def run_and_stop_on_exit() -> AsyncGenerator[None, None]:
"""
Starts a package server for the duration of the context block, if one is not currently running,
and stops and deregisters it on exit.
"""
if await is_running():
yield
return
try:
repo_name = ephemeral_repository_name()
print(
"You do not seem to have a package server running. "
+ "A temporary one will be started for the duration of this execution."
)
server = await start(repo_name)
except PackageServingException as e:
raise PackageServingCLIException(
f"Error: {e}\nError: Failed to start the temporary package server. "
+ "You may need to manually start one via `fx serve`."
)
try:
yield
finally:
try:
await deregister(repo_name)
finally:
server.terminate()
await server.wait()
# Sending SIGTERM doesn't seem to clean up child processes, so use `ffx` to stop the
# package server we just started for good measure.
await stop(repo_name)