shareadb 0.1.0__tar.gz

shareadb-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: shareadb
+Version: 0.1.0
+Summary: Share local adb devices with remote users via TCP proxy
+Requires-Python: >=3.8

shareadb-0.1.0/README.md

@@ -0,0 +1,139 @@
+# 功能需求
+
+共享本地adb设备给其他用户使用。
+
+## 需要考虑的问题
+
+1. 多设备管理: 支持同时连接和管理多个adb设备。每个设备可以分配不同的端口号进行adb连接。
+2. 跨平台支持, 需要支持windows, linux等操作系统
+3. 一旦开启后，会记录已经开启的连接，如果设备断开后，可以自动进行重连(周期比如间隔5s检测设备是否已经连接上了, 用于维护连接的稳定性). 通知链接的断开和重新连接状态.
+4. 可以针对单个已经连接的设备进行操作.
+
+## 基础功能的实现步骤
+
+检测adb，如果没有安装adb命令，那么则需要提示用户安装或者输入adb路径
+
+当单个设备时
+```bash
+adb shell setprop persist.adb.tcp.port 5555
+adb shell stop adbd
+adb shell start adbd
+adb forward tcp:6000 tcp:5555
+```
+
+多个设备希望端口号可以慢慢自增
+
+最终还需要在本地启动一个代理，允许其他设备连接当前设备的IP来访问adb功能.
+
+类似:
+```bash
+socat -s tcp4-listen:7000,reuseaddr,fork tcp-connect:127.0.0.1:6000
+```
+
+不过不建议直接使用socat, 而是使用python利用socket来实现一个属于自己的代理，这样可以实现跨平台.
+
+## 项目结构
+
+```
+pyproject.toml        # 项目元数据与命令行入口
+src/shareadb/         # Python 源码目录
+  __init__.py
+  adb_client.py       # 封装 adb 命令的异步客户端
+  cli.py              # 命令行入口，负责参数解析与事件循环
+  device_manager.py   # 设备会话管理、端口分配与自动重连逻辑
+  tcp_proxy.py        # 基于 asyncio 的 TCP 代理实现
+```
+
+## 使用说明
+
+1. 确保本机已安装 adb 并可以在命令行中访问，或在执行时使用 `--adb-path` 指定 adb 的完整路径。
+2. 在仓库根目录执行：
+
+```bash
+python -m shareadb.cli --poll-interval 5 --status-interval 30
+```
+
+常用参数：
+- `--listen-host`: 代理监听的地址，默认 `0.0.0.0`
+- `--forward-base-port`: adb forward 起始端口，默认 `6000`
+- `--proxy-base-port`: TCP 代理起始端口，默认 `7000`
+- `--include`: 仅管理指定序列号的设备，例如 `--include SERIAL1 SERIAL2`
+
+3. 程序会每隔 `poll-interval` 秒检测设备状态：
+   - 新设备上线时自动配置 `adb tcp`、建立端口转发并启动本地代理；
+   - 设备断开时释放 forward 与代理，下次检测到设备重新连接时继续复用历史端口；
+   - `status-interval` 控制定期输出设备状态日志，设置为 `0` 可关闭。
+   - 设备连接成功后，会自动显示本机的所有可访问 IP 地址和对应的连接指令。
+
+远端用户只需连接到 `listen-host:proxy_port` 即可访问对应设备的 adb。每台设备都会分配一对唯一的 forward 与代理端口，并在设备重连后保持一致。
+
+## 连接信息示例
+
+当设备成功连接后，程序会自动输出类似以下信息：
+
+```
+============================================================
+ADB devices are now ready for remote connection!
+Remote users can connect using:
+
+Device: abc123def456
+  Model: Pixel 6
+  Proxy port: 7000
+  Connection commands:
+    adb connect 10.0.28.15:7000
+    adb connect 192.168.1.100:7000
+
+Note: Use the appropriate IP address that is accessible from the remote machine
+============================================================
+```
+
+无需手动查找本机 IP，程序会自动检测所有可用的网络接口 IP 地址，方便远端用户选择合适的地址进行连接。
+
+## 打包和发布
+
+### 构建分发包
+
+```bash
+# 安装构建工具
+pip install build twine
+
+# 构建分发包
+python -m build
+```
+
+构建完成后，会在 `dist/` 目录下生成 `.tar.gz` 和 `.whl` 文件。
+
+### 上传到 PyPI
+
+首先确保你已经注册了 PyPI 账号并配置了账号信息：
+
+```bash
+# 上传到测试 PyPI（用于测试）
+python -m twine upload --repository testpypi dist/*
+
+# 上传到正式 PyPI
+python -m twine upload dist/*
+```
+
+### 从 PyPI 安装
+
+```bash
+# 从正式 PyPI 安装
+pip install shareadbpy
+
+# 从测试 PyPI 安装
+pip install --index-url https://test.pypi.org/simple/ shareadbpy
+```
+
+安装后可以直接使用命令：
+
+```bash
+shareadbpy --poll-interval 5 --status-interval 30
+```
+
+## 已测试场景
+
+- Ubuntu 下的单设备移除和恢复
+- Ubuntu 下的双设备移除和恢复
+- 使用 `--include` 参数在双设备环境下只共享指定设备
+- 基础功能在 Linux 系统下运行正常

shareadb-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shareadb"
+version = "0.1.0"
+description = "Share local adb devices with remote users via TCP proxy"
+requires-python = ">=3.8"
+# No external dependencies required; uses Python standard library only.
+dependencies = []
+
+[project.scripts]
+shareadbpy = "shareadb.cli:main"

shareadb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shareadb-0.1.0/src/shareadb/__init__.py

@@ -0,0 +1,5 @@
+"""shareadb package: share local adb devices via TCP proxies."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

shareadb-0.1.0/src/shareadb/adb_client.py

@@ -0,0 +1,210 @@
+"""Helpers for interacting with the adb command line tool."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Union
+
+_LOG = logging.getLogger(__name__)
+
+
+@dataclass
+class ADBCommandResult:
+    """Result wrapper for adb command executions."""
+
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+class ADBCommandError(RuntimeError):
+    """Raised when an adb command exits with a non-zero code."""
+
+    def __init__(self, command: Sequence[str], result: ADBCommandResult):
+        message = (
+            f"Command {' '.join(command)} failed with exit code {result.returncode}.\n"
+            f"stdout: {result.stdout}\n"
+            f"stderr: {result.stderr}"
+        )
+        super().__init__(message)
+        self.command = list(command)
+        self.result = result
+
+
+@dataclass
+class ADBDeviceInfo:
+    """Represents a single adb device entry."""
+
+    serial: str
+    state: str
+    product: Optional[str] = None
+    model: Optional[str] = None
+    device: Optional[str] = None
+    transport_id: Optional[str] = None
+    extra: Optional[Dict[str, str]] = None
+
+    @property
+    def is_ready(self) -> bool:
+        """Whether this device is in an operational state."""
+
+        return self.state == "device"
+
+
+class ADBClient:
+    """Thin asynchronous wrapper around the adb executable."""
+
+    def __init__(self, adb_path: Union[Path, str]):
+        self._adb_path = Path(adb_path)
+
+    @property
+    def adb_path(self) -> Path:
+        return self._adb_path
+
+    @staticmethod
+    def detect(default: Optional[str] = None) -> Path:
+        """Resolve the adb executable location.
+
+        Args:
+            default: Optional path provided by the user.
+
+        Returns:
+            A ``Path`` pointing to the adb executable.
+
+        Raises:
+            FileNotFoundError: If adb cannot be located.
+        """
+
+        if default:
+            candidate = Path(default).expanduser()
+            if candidate.is_file():
+                return candidate
+            raise FileNotFoundError(f"Provided adb path does not exist: {candidate}")
+
+        resolved = shutil.which("adb")
+        if not resolved:
+            raise FileNotFoundError(
+                "Could not locate 'adb'. Install Android Platform Tools or provide --adb-path."
+            )
+        return Path(resolved)
+
+    async def run(
+        self,
+        args: Sequence[str],
+        *,
+        device_serial: Optional[str] = None,
+        timeout: Optional[float] = None,
+        check: bool = True,
+    ) -> ADBCommandResult:
+        """Execute an adb sub-command asynchronously."""
+
+        cmd: List[str] = [str(self._adb_path)]
+        if device_serial:
+            cmd += ["-s", device_serial]
+        cmd.extend(args)
+
+        _LOG.debug("Running adb command: %s", " ".join(cmd))
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        try:
+            stdout_raw, stderr_raw = await asyncio.wait_for(process.communicate(), timeout=timeout)
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise
+
+        stdout = stdout_raw.decode("utf-8", errors="replace").strip()
+        stderr = stderr_raw.decode("utf-8", errors="replace").strip()
+        result = ADBCommandResult(stdout=stdout, stderr=stderr, returncode=process.returncode)
+
+        if check and process.returncode != 0:
+            raise ADBCommandError(cmd, result)
+        if result.stderr:
+            _LOG.debug("adb stderr: %s", result.stderr)
+        return result
+
+    async def shell(
+        self,
+        device_serial: str,
+        shell_args: Iterable[str],
+        *,
+        timeout: Optional[float] = None,
+    ) -> ADBCommandResult:
+        """Run an adb shell command on a specific device."""
+
+        args = ["shell", *shell_args]
+        return await self.run(args, device_serial=device_serial, timeout=timeout)
+
+    async def forward(
+        self,
+        device_serial: str,
+        local_port: int,
+        remote_port: int,
+        *,
+        replace: bool = True,
+    ) -> None:
+        """Create or replace a port forward between host and device."""
+
+        if replace:
+            try:
+                await self.run(
+                    ["forward", "--remove", f"tcp:{local_port}"],
+                    device_serial=device_serial,
+                    check=False,
+                )
+            except Exception:  # pragma: no cover - defensive; run() already suppresses via check=False
+                _LOG.debug("Ignoring failure removing existing forward for port %s", local_port)
+        await self.run(
+            ["forward", f"tcp:{local_port}", f"tcp:{remote_port}"],
+            device_serial=device_serial,
+        )
+
+    async def remove_forward(self, device_serial: str, local_port: int) -> None:
+        """Remove an adb forward if it exists."""
+
+        await self.run(
+            ["forward", "--remove", f"tcp:{local_port}"],
+            device_serial=device_serial,
+            check=False,
+        )
+
+    async def list_devices(self) -> List[ADBDeviceInfo]:
+        """Return all devices reported by ``adb devices -l``."""
+
+        result = await self.run(["devices", "-l"])
+        return _parse_device_list(result.stdout)
+
+
+def _parse_device_list(raw: str) -> List[ADBDeviceInfo]:
+    devices: List[ADBDeviceInfo] = []
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line or line.startswith("List of devices attached"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        serial, state, *rest = parts
+        fields: dict[str, str] = {}
+        for item in rest:
+            if ":" in item:
+                key, value = item.split(":", 1)
+                fields[key] = value
+        devices.append(
+            ADBDeviceInfo(
+                serial=serial,
+                state=state,
+                product=fields.get("product"),
+                model=fields.get("model"),
+                device=fields.get("device"),
+                transport_id=fields.get("transport_id"),
+                extra={k: v for k, v in fields.items() if k not in {"product", "model", "device", "transport_id"}},
+            )
+        )
+    return devices

shareadb-0.1.0/src/shareadb/cli.py

@@ -0,0 +1,255 @@
+"""Command line entry point for shareadb."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import signal
+import socket
+from typing import Iterable, List, Optional
+
+from .adb_client import ADBClient
+from .device_manager import DeviceManager, DeviceStatus
+
+
+def get_local_ips() -> List[str]:
+    """Get all local IP addresses from network interfaces."""
+    ips = []
+    try:
+        # Try to get IPs from all network interfaces
+        hostname = socket.gethostname()
+        addr_info = socket.getaddrinfo(hostname, None, proto=socket.IPPROTO_TCP)
+        
+        # Also try to get IPs directly from hostname
+        try:
+            hostname_ip = socket.gethostbyname(hostname)
+            addr_info.extend([(socket.AF_INET, socket.SOCK_STREAM, 6, '', (hostname_ip, 0))])
+        except:
+            pass
+        
+        for info in addr_info:
+            ip = info[4][0] if info[4] else None
+            if ip:
+                # Filter out IPv6 and loopback addresses
+                if ':' not in ip and not ip.startswith('127.'):
+                    if ip not in ips:
+                        ips.append(ip)
+                        
+        # If still no IPs, try common interface names
+        if not ips:
+            interfaces = ['eth0', 'en0', 'wlan0', 'enp*', 'wlp*']
+            for interface in interfaces:
+                try:
+                    # Try to get IP by creating a socket and binding to interface
+                    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+                    # This won't actually connect, just get interface info
+                    s.connect(('8.8.8.8', 80))
+                    ip = s.getsockname()[0]
+                    s.close()
+                    if ip and not ip.startswith('127.') and ip not in ips:
+                        ips.append(ip)
+                        break
+                except:
+                    continue
+    except Exception as exc:
+        _LOG.debug("Error detecting local IPs: %s", exc)
+    
+    # Fallback to common local network IPs
+    if not ips:
+        _LOG.warning("Could not detect local IP address, using 0.0.0.0")
+        ips = ['0.0.0.0']
+    
+    return sorted(ips)
+
+_LOG = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Share local adb devices with remote users")
+    parser.add_argument("--adb-path", help="Path to adb executable; defaults to PATH lookup")
+    parser.add_argument("--listen-host", default="0.0.0.0", help="Host/IP for proxy listeners")
+    parser.add_argument("--device-tcp-port", type=int, default=5555, help="adb tcp port configured on devices")
+    parser.add_argument(
+        "--forward-base-port",
+        type=int,
+        default=6000,
+        help="First local port for adb forward; increments per device",
+    )
+    parser.add_argument(
+        "--proxy-base-port",
+        type=int,
+        default=7000,
+        help="First proxy listening port; increments per device",
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=5.0,
+        help="Seconds between adb device polling cycles",
+    )
+    parser.add_argument(
+        "--include",
+        nargs="*",
+        help="Optional list of device serials to manage (default: all detected devices)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Logging verbosity",
+    )
+    parser.add_argument(
+        "--status-interval",
+        type=float,
+        default=30.0,
+        help="Seconds between periodic status logs (0 to disable)",
+    )
+    return parser
+
+
+async def main_async(args: argparse.Namespace) -> None:
+    adb_path = ADBClient.detect(args.adb_path)
+    adb_client = ADBClient(adb_path)
+
+    manager = DeviceManager(
+        adb_client,
+        listen_host=args.listen_host,
+        device_tcp_port=args.device_tcp_port,
+        forward_base_port=args.forward_base_port,
+        proxy_base_port=args.proxy_base_port,
+        poll_interval=args.poll_interval,
+        include_serials=args.include,
+    )
+
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+
+    def _request_shutdown() -> None:
+        _LOG.info("Shutdown requested via signal")
+        stop_event.set()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, _request_shutdown)
+        except NotImplementedError:
+            # Windows event loop may not support signal handlers; fallback to default behavior.
+            pass
+
+    await manager.start()
+
+    status_task: Optional[asyncio.Task[None]] = None
+    if args.status_interval > 0:
+        status_task = asyncio.create_task(_status_logger(manager, args.status_interval))
+
+    # Monitor devices and print connection info when they become ready
+    print_task = asyncio.create_task(_print_connection_on_ready(manager, args.listen_host, args.proxy_base_port))
+
+    try:
+        await stop_event.wait()
+    finally:
+        if status_task:
+            status_task.cancel()
+            await asyncio.gather(status_task, return_exceptions=True)
+        print_task.cancel()
+        await asyncio.gather(print_task, return_exceptions=True)
+        await manager.stop()
+
+
+async def _status_logger(manager: DeviceManager, interval: float) -> None:
+    try:
+        while True:
+            await asyncio.sleep(interval)
+            statuses = manager.statuses()
+            if not statuses:
+                _LOG.info("No active adb devices detected")
+            else:
+                for status in statuses:
+                    _LOG.info("%s", _format_status(status))
+    except asyncio.CancelledError:
+        return
+
+
+async def _print_connection_on_ready(manager: DeviceManager, listen_host: str, proxy_base_port: int) -> None:
+    """Monitor devices and print connection info when they become ready."""
+    # Track running devices to avoid duplicate prints
+    seen_running = set()
+    
+    while not manager._stop_event.is_set():
+        statuses = manager.statuses()
+        has_new = False
+        
+        for status in statuses:
+            if status.state.value == "running" and status.serial not in seen_running:
+                seen_running.add(status.serial)
+                has_new = True
+        
+        # Print connection info if we have new running devices
+        if has_new:
+            _print_connection_info(manager, listen_host, proxy_base_port)
+        
+        # Wait a bit before checking again
+        await asyncio.sleep(1.0)
+
+
+def _print_connection_info(manager: DeviceManager, listen_host: str, proxy_base_port: int) -> None:
+    """Print connection information for all active devices."""
+    local_ips = get_local_ips()
+    statuses = manager.statuses()
+    
+    if not statuses:
+        _LOG.info("No adb devices detected yet. Waiting for devices...")
+        return
+    
+    _LOG.info("=" * 60)
+    _LOG.info("ADB devices are now ready for remote connection!")
+    _LOG.info("Remote users can connect using:")
+    _LOG.info("")
+    
+    for status in statuses:
+        if status.state.value == "running":
+            _LOG.info("Device: %s", status.serial)
+            if status.model:
+                _LOG.info("  Model: %s", status.model)
+            _LOG.info("  Proxy port: %d", status.proxy_port)
+            _LOG.info("  Connection commands:")
+            for ip in local_ips:
+                _LOG.info("    adb connect %s:%d", ip, status.proxy_port)
+            _LOG.info("")
+    
+    _LOG.info("Note: Use the appropriate IP address that is accessible from the remote machine")
+    _LOG.info("=" * 60)
+
+
+def _format_status(status: DeviceStatus) -> str:
+    parts: List[str] = [
+        f"serial={status.serial}",
+        f"state={status.state.value}",
+        f"proxy={status.proxy_port}",
+        f"forward={status.forward_port}",
+        f"tcp={status.tcp_port}",
+    ]
+    if status.model:
+        parts.append(f"model={status.model}")
+    if status.product:
+        parts.append(f"product={status.product}")
+    if status.last_error:
+        parts.append(f"error={status.last_error}")
+    return " ".join(parts)
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+    )
+    try:
+        asyncio.run(main_async(args))
+    except KeyboardInterrupt:
+        _LOG.info("Interrupted by user")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shareadb-0.1.0/src/shareadb/device_manager.py

@@ -0,0 +1,286 @@
+"""Device management and orchestration for adb sharing."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, Iterable, List, Optional, Sequence
+
+from .adb_client import ADBClient, ADBCommandError, ADBDeviceInfo
+from .tcp_proxy import TCPProxyServer
+
+_LOG = logging.getLogger(__name__)
+
+
+@dataclass
+class DevicePorts:
+    """Ports reserved for a specific device."""
+
+    forward: int
+    proxy: int
+
+
+class SessionState(Enum):
+    WAITING = "waiting"
+    RUNNING = "running"
+    ERROR = "error"
+
+
+@dataclass
+class DeviceStatus:
+    """Public view of a device session."""
+
+    serial: str
+    state: SessionState
+    forward_port: int
+    proxy_port: int
+    tcp_port: int
+    model: Optional[str] = None
+    product: Optional[str] = None
+    last_error: Optional[str] = None
+
+
+class ADBDeviceSession:
+    """Lifecycle handler for a single adb device."""
+
+    def __init__(
+        self,
+        adb_client: ADBClient,
+        serial: str,
+        *,
+        device_tcp_port: int,
+        forward_port: int,
+        proxy_port: int,
+        listen_host: str,
+    ) -> None:
+        self._adb = adb_client
+        self._serial = serial
+        self._device_tcp_port = device_tcp_port
+        self._forward_port = forward_port
+        self._proxy_port = proxy_port
+        self._listen_host = listen_host
+        self._proxy = TCPProxyServer(
+            listen_host,
+            proxy_port,
+            "127.0.0.1",
+            forward_port,
+            name=f"{serial}:{proxy_port}->{forward_port}",
+        )
+        self._lock = asyncio.Lock()
+        self._state = SessionState.WAITING
+        self._last_error: Optional[str] = None
+        self._last_info: Optional[ADBDeviceInfo] = None
+
+    @property
+    def serial(self) -> str:
+        return self._serial
+
+    @property
+    def state(self) -> SessionState:
+        return self._state
+
+    @property
+    def forward_port(self) -> int:
+        return self._forward_port
+
+    @property
+    def proxy_port(self) -> int:
+        return self._proxy_port
+
+    @property
+    def tcp_port(self) -> int:
+        return self._device_tcp_port
+
+    @property
+    def last_error(self) -> Optional[str]:
+        return self._last_error
+
+    def describe(self) -> DeviceStatus:
+        info = self._last_info
+        return DeviceStatus(
+            serial=self._serial,
+            state=self._state,
+            forward_port=self._forward_port,
+            proxy_port=self._proxy_port,
+            tcp_port=self._device_tcp_port,
+            model=info.model if info else None,
+            product=info.product if info else None,
+            last_error=self._last_error,
+        )
+
+    async def ensure_running(self, info: ADBDeviceInfo) -> None:
+        async with self._lock:
+            self._last_info = info
+            if self._state == SessionState.RUNNING:
+                return
+            try:
+                await self._start()
+                self._state = SessionState.RUNNING
+                self._last_error = None
+            except Exception as exc:  # pragma: no cover - relies on adb/hardware failures
+                self._last_error = str(exc)
+                self._state = SessionState.ERROR
+                _LOG.error("Failed to enable adb sharing for %s: %s", self._serial, exc)
+                await self._teardown_forward()
+                raise
+
+    async def mark_unavailable(self, reason: str) -> None:
+        async with self._lock:
+            if self._state == SessionState.WAITING:
+                return
+            _LOG.info("Device %s unavailable (%s); tearing down proxy", self._serial, reason)
+            await self._stop()
+            self._state = SessionState.WAITING
+
+    async def shutdown(self) -> None:
+        async with self._lock:
+            await self._stop()
+            self._state = SessionState.WAITING
+
+    async def _start(self) -> None:
+        _LOG.info(
+            "Configuring adb over TCP for device %s (forward tcp:%s -> tcp:%s)",
+            self._serial,
+            self._forward_port,
+            self._device_tcp_port,
+        )
+        await self._adb.shell(
+            self._serial,
+            ["setprop", "persist.adb.tcp.port", str(self._device_tcp_port)],
+        )
+        await self._adb.forward(self._serial, self._forward_port, self._device_tcp_port)
+        await self._proxy.start()
+        _LOG.info(
+            "Device %s shared on %s:%s (forward tcp:%s -> tcp:%s)",
+            self._serial,
+            self._listen_host,
+            self._proxy_port,
+            self._forward_port,
+            self._device_tcp_port,
+        )
+
+    async def _stop(self) -> None:
+        await self._proxy.stop()
+        await self._teardown_forward()
+
+    async def _teardown_forward(self) -> None:
+        try:
+            await self._adb.remove_forward(self._serial, self._forward_port)
+        except ADBCommandError as exc:  # pragma: no cover - occurs on unexpected adb failures
+            _LOG.debug("remove_forward failed for %s: %s", self._serial, exc)
+
+
+class DeviceManager:
+    """Coordinates adb devices and associated proxy sessions."""
+
+    def __init__(
+        self,
+        adb_client: ADBClient,
+        *,
+        listen_host: str,
+        device_tcp_port: int,
+        forward_base_port: int,
+        proxy_base_port: int,
+        poll_interval: float,
+        include_serials: Optional[Sequence[str]] = None,
+    ) -> None:
+        self._adb = adb_client
+        self._listen_host = listen_host
+        self._device_tcp_port = device_tcp_port
+        self._poll_interval = poll_interval
+        self._include_serials = set(include_serials or [])
+        self._sessions: Dict[str, ADBDeviceSession] = {}
+        self._port_state: Dict[str, DevicePorts] = {}
+        self._next_forward = forward_base_port
+        self._next_proxy = proxy_base_port
+        self._task: Optional[asyncio.Task[None]] = None
+        self._stop_event = asyncio.Event()
+
+    async def start(self) -> None:
+        if self._task:
+            return
+        self._stop_event.clear()
+        self._task = asyncio.create_task(self._run_loop())
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+        if self._task:
+            await self._task
+            self._task = None
+        await self._shutdown_sessions()
+
+    async def _run_loop(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                await self._sync_devices()
+            except Exception as exc:  # pragma: no cover - ensures background loop resilience
+                _LOG.exception("Unhandled error during device sync: %s", exc)
+            try:
+                await asyncio.wait_for(self._stop_event.wait(), timeout=self._poll_interval)
+            except asyncio.TimeoutError:
+                continue
+
+    async def _sync_devices(self) -> None:
+        try:
+            devices = await self._adb.list_devices()
+        except FileNotFoundError:
+            _LOG.error("adb executable not found during sync")
+            return
+        except ADBCommandError as exc:
+            _LOG.error("Failed to list devices: %s", exc)
+            return
+
+        if self._include_serials:
+            devices = [d for d in devices if d.serial in self._include_serials]
+
+        ready_devices = {device.serial: device for device in devices if device.is_ready}
+        seen_serials = set(devices_by_serial(devices))
+
+        # Start or refresh sessions for ready devices.
+        for serial, device in ready_devices.items():
+            session = self._sessions.get(serial)
+            if not session:
+                ports = self._ensure_ports(serial)
+                session = ADBDeviceSession(
+                    self._adb,
+                    serial,
+                    device_tcp_port=self._device_tcp_port,
+                    forward_port=ports.forward,
+                    proxy_port=ports.proxy,
+                    listen_host=self._listen_host,
+                )
+                self._sessions[serial] = session
+            try:
+                await session.ensure_running(device)
+            except Exception:
+                # ``ensure_running`` already logged details; keep looping for retries.
+                continue
+
+        # Tear down sessions for devices no longer available.
+        for serial, session in list(self._sessions.items()):
+            if serial not in ready_devices and session.state == SessionState.RUNNING:
+                reason = "not listed" if serial not in seen_serials else "not ready"
+                await session.mark_unavailable(reason)
+
+    async def _shutdown_sessions(self) -> None:
+        for session in list(self._sessions.values()):
+            await session.shutdown()
+
+    def _ensure_ports(self, serial: str) -> DevicePorts:
+        ports = self._port_state.get(serial)
+        if ports:
+            return ports
+        ports = DevicePorts(forward=self._next_forward, proxy=self._next_proxy)
+        self._next_forward += 1
+        self._next_proxy += 1
+        self._port_state[serial] = ports
+        _LOG.debug("Allocated ports for %s: forward=%s proxy=%s", serial, ports.forward, ports.proxy)
+        return ports
+
+    def statuses(self) -> List[DeviceStatus]:
+        return [session.describe() for session in self._sessions.values()]
+
+
+def devices_by_serial(devices: Iterable[ADBDeviceInfo]) -> List[str]:
+    return [device.serial for device in devices]

shareadb-0.1.0/src/shareadb/tcp_proxy.py

@@ -0,0 +1,119 @@
+"""Async TCP proxy to bridge clients to forwarded adb ports."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Optional
+
+_LOG = logging.getLogger(__name__)
+
+
+class TCPProxyServer:
+    """Bidirectional TCP proxy implemented with asyncio streams."""
+
+    def __init__(
+        self,
+        listen_host: str,
+        listen_port: int,
+        target_host: str,
+        target_port: int,
+        *,
+        name: Optional[str] = None,
+    ) -> None:
+        self._listen_host = listen_host
+        self._listen_port = listen_port
+        self._target_host = target_host
+        self._target_port = target_port
+        self._server: Optional[asyncio.AbstractServer] = None
+        self._client_tasks: set[asyncio.Task[None]] = set()
+        self._name = name or f"proxy:{listen_port}->{target_port}"
+        self._lock = asyncio.Lock()
+
+    @property
+    def address(self) -> tuple[str, int]:
+        return self._listen_host, self._listen_port
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    async def start(self) -> None:
+        async with self._lock:
+            if self._server:
+                return
+            self._server = await asyncio.start_server(
+                self._handle_client,
+                host=self._listen_host,
+                port=self._listen_port,
+            )
+            addr = ", ".join(str(sock.getsockname()) for sock in self._server.sockets or [])
+            _LOG.info("Started proxy %s listening on %s", self._name, addr)
+
+    async def stop(self) -> None:
+        async with self._lock:
+            if not self._server:
+                return
+            server, self._server = self._server, None
+            server.close()
+            await server.wait_closed()
+            for task in list(self._client_tasks):
+                task.cancel()
+            if self._client_tasks:
+                await asyncio.gather(*self._client_tasks, return_exceptions=True)
+            self._client_tasks.clear()
+            _LOG.info("Stopped proxy %s", self._name)
+
+    async def _handle_client(
+        self,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+    ) -> None:
+        peer = client_writer.get_extra_info("peername")
+        _LOG.debug("Accepted connection %s -> %s", peer, self._name)
+        try:
+            upstream_reader, upstream_writer = await asyncio.open_connection(
+                host=self._target_host,
+                port=self._target_port,
+            )
+        except Exception as exc:  # pragma: no cover - network failures hard to deterministically test
+            _LOG.warning(
+                "Proxy %s failed to connect to target %s:%s: %s",
+                self._name,
+                self._target_host,
+                self._target_port,
+                exc,
+            )
+            client_writer.close()
+            await client_writer.wait_closed()
+            return
+
+        async def pipe(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+            try:
+                while True:
+                    data = await reader.read(65536)
+                    if not data:
+                        break
+                    writer.write(data)
+                    await writer.drain()
+            except asyncio.CancelledError:  # Propagate cancellation cleanly
+                raise
+            except Exception as exc:  # pragma: no cover - defensive logging
+                _LOG.debug("Proxy %s pipe error: %s", self._name, exc)
+            finally:
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+        task_down = asyncio.create_task(pipe(client_reader, upstream_writer))
+        task_up = asyncio.create_task(pipe(upstream_reader, client_writer))
+        grouped = asyncio.gather(task_down, task_up, return_exceptions=True)
+        self._client_tasks.add(task_down)
+        self._client_tasks.add(task_up)
+        try:
+            await grouped
+        finally:
+            self._client_tasks.discard(task_down)
+            self._client_tasks.discard(task_up)
+            _LOG.debug("Closed connection %s -> %s", peer, self._name)

shareadb-0.1.0/src/shareadb.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: shareadb
+Version: 0.1.0
+Summary: Share local adb devices with remote users via TCP proxy
+Requires-Python: >=3.8

shareadb-0.1.0/src/shareadb.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/shareadb/__init__.py
+src/shareadb/adb_client.py
+src/shareadb/cli.py
+src/shareadb/device_manager.py
+src/shareadb/tcp_proxy.py
+src/shareadb.egg-info/PKG-INFO
+src/shareadb.egg-info/SOURCES.txt
+src/shareadb.egg-info/dependency_links.txt
+src/shareadb.egg-info/entry_points.txt
+src/shareadb.egg-info/top_level.txt

shareadb-0.1.0/src/shareadb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shareadb-0.1.0/src/shareadb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shareadbpy = shareadb.cli:main

shareadb-0.1.0/src/shareadb.egg-info/top_level.txt

@@ -0,0 +1 @@
+shareadb