adbproxy 0.1.0__py3-none-any.whl

adbproxy/observers/sync.py

@@ -0,0 +1,550 @@
+import os
+import re
+import struct
+import threading
+
+from adbproxy.config import (
+    MAX_SYNC_FILE,
+    _DENT_V1_SIZE,
+    _DENT_V2_FMT,
+    _DENT_V2_SIZE,
+    _STAT_V1_SIZE,
+    _STAT_V2_FMT,
+    _STAT_V2_SIZE,
+)
+from adbproxy.protocols.payload.sync import SyncWireDecoder, plan_sync_frame
+from adbproxy.runtime.capture import open_unique_capture, reserve_unique_capture_path
+
+
+SYNC_DATA_MAX = 64 * 1024
+
+
+class SyncSession:
+    """per-conn sync 二进制协议状态机 + 文件捕获落盘。
+
+    分帧由 pure ``SyncWireDecoder`` / ``plan_sync_frame`` 完成；本类持有
+    方向状态、捕获与压缩旁路。
+    """
+
+    def __init__(self, logger, files_dir, capture_enabled=True):
+        self.logger = logger
+        self.files_dir = files_dir
+        self.capture_enabled = capture_enabled
+        self.lock = threading.Lock()
+        self.op = None  # "SEND"=push / "RECV"=pull / None
+        self.remote_path = None
+        self.basename = None
+        self.remote_size = (
+            None  # pull 的 STAT/STA2 响应已解析 size（命名用，pull 不取 mtime）
+        )
+        self.accumulated = 0  # 已收文件字节数（P4：解压后长度，命名 size 段用）
+        self.file_fp = None  # 落盘文件句柄（"wb" 覆写，时间戳防重名）
+        self.capture_path = None
+        # sync 是双向协议：两个方向必须各自重组半帧，不能用同一缓冲拼接。
+        self.c_wire = SyncWireDecoder()
+        self.s_wire = SyncWireDecoder()
+        # 兼容测试/调用方：暴露 frame_buf 视图别名（指向 pure codec 缓冲）
+        self.c_frame_buf = self.c_wire.buf
+        self.s_frame_buf = self.s_wire.buf
+        self.c_bypass = False
+        self.s_bypass = False
+        self.bypass = False  # 兼容汇总标志；解析时仅禁用发生错误的方向。
+        self.expecting = None  # "req"/"data_c"/"data_s"/"idle"/None
+        self.awaiting_details = (
+            None  # v2: None / "send" / "recv"（SND2/RCV2 双发第二帧判据）
+        )
+        # P4: sync v2 压缩旁路解压（仅作用于落盘 _write_capture，sendall 原样压缩字节透传）
+        self.compression = None  # None/"zstd"/"lz4"/"brotli"
+        self.decoder = None  # 流式解压器实例（zstandard.ZstdDecompressionObj / lz4.frame / brotli.Decompressor）
+        self.decoder_lib_missing = (
+            False  # 解压库未装/异常降级标志（原样落盘压缩字节 + warning）
+        )
+        self.decoder_fallback = None  # None/"unavailable"/"failed"
+        self.bypass = False  # 解析异常降级标志
+        self.capture_overflow = False  # 单文件超 MAX_SYNC_FILE 后停止写盘
+
+    @property
+    def active(self):
+        return self.expecting is not None
+
+    def activate(self):
+        """由 Connection 在 client 首帧 service 命中 sync: 时调用，显式置 expecting 打破循环依赖。"""
+        with self.lock:
+            self.expecting = "req"
+            self.op = None
+            self.awaiting_details = None
+            self.c_wire.reset()
+            self.s_wire.reset()
+            self.c_frame_buf = self.c_wire.buf
+            self.s_frame_buf = self.s_wire.buf
+            self.c_bypass = False
+            self.s_bypass = False
+            self.bypass = False
+
+    def on_client(self, data):
+        with self.lock:
+            self._feed(data, "c")
+
+    def on_server(self, data):
+        with self.lock:
+            self._feed(data, "s")
+
+    def _feed(self, data, side):
+        """按 (id,方向,状态) 分帧。pure codec 持缓冲；每帧后刷新 awaiting_details。"""
+        bypass_attr = "c_bypass" if side == "c" else "s_bypass"
+        wire = self.c_wire if side == "c" else self.s_wire
+        if getattr(self, bypass_attr) or wire.bypass:
+            return
+        wire.extend(data)
+        while True:
+            frame = wire.try_take_frame(
+                lambda id_, s=side: plan_sync_frame(id_, s, self.awaiting_details)
+            )
+            if frame is None:
+                if wire.bypass:
+                    setattr(self, bypass_attr, True)
+                    self.bypass = self.c_bypass or self.s_bypass
+                    reason = wire.degrade_reason or "framing"
+                    self.logger.debug(
+                        f"[!] sync {reason} (side={side}, expecting={self.expecting}, "
+                        f"awaiting={self.awaiting_details}), degrading"
+                    )
+                return
+            self._on_frame(frame.id, frame.raw, side)
+            if getattr(self, bypass_attr):
+                return
+
+    def _on_frame(self, id_, frame, side):
+        if side == "c":
+            self._on_client_frame(id_, frame)
+        else:
+            self._on_server_frame(id_, frame)
+
+    def _on_client_frame(self, id_, frame):
+        if id_ in (b"STA2", b"LST2", b"STAT", b"LIST"):
+            # stat/list 查询请求：8+path，无文件落盘语义，保持 expecting 不变
+            path = frame[8:].decode("utf-8", errors="ignore")
+            self.logger.debug(f"[sync {id_.decode()} req]: path={path}")
+            return
+        if id_ == b"SEND":  # v1 push 路径请求
+            path = frame[8:].decode("utf-8", errors="ignore")
+            if "," in path:  # v1 SEND path 末尾带 ,mode
+                path = path.rsplit(",", 1)[0]
+            self._start_push(path, v2=False)
+            return
+        if id_ == b"RECV":  # v1 pull 路径请求
+            path = frame[8:].decode("utf-8", errors="ignore")
+            self._start_pull(path, v2=False)
+            return
+        if id_ == b"SND2":
+            if self.awaiting_details == "send":
+                # 双发第二帧 = sync_send_v2(12B id+mode+flags)
+                mode = struct.unpack_from("<I", frame, 4)[0]
+                flags = struct.unpack_from("<I", frame, 8)[0]
+                self.logger.debug(f"[sync send_v2 details]: mode={mode} flags={flags}")
+                # P4: push DATA 是 client→server 压缩字节，proxy 旁路解压落盘（sendall 原样透传）
+                if not self._setup_decoder(flags):
+                    self.c_bypass = True
+                    self.bypass = self.c_bypass or self.s_bypass
+                    return
+                self.awaiting_details = None
+                self.expecting = "data_c"
+            else:
+                path = frame[8:].decode("utf-8", errors="ignore")
+                self._start_push(path, v2=True)
+            return
+        if id_ == b"RCV2":
+            if self.awaiting_details == "recv":
+                flags = struct.unpack_from("<I", frame, 4)[0]
+                self.logger.debug(f"[sync recv_v2 details]: flags={flags}")
+                # P4: pull DATA 是 server→client 压缩字节，proxy 旁路解压落盘（sendall 原样透传）
+                if not self._setup_decoder(flags):
+                    self.c_bypass = True
+                    self.bypass = self.c_bypass or self.s_bypass
+                    return
+                self.awaiting_details = None
+                self.expecting = "data_s"
+            else:
+                path = frame[8:].decode("utf-8", errors="ignore")
+                self._start_pull(path, v2=True)
+            return
+        if id_ == b"DATA":
+            if self.expecting == "data_c":
+                size = struct.unpack_from("<I", frame, 4)[0]
+                payload = frame[8 : 8 + size]
+                # P4: 旁路解压后写盘 + accumulated 累加解压后长度（sendall 原样压缩字节已更早透传）
+                self._feed_data(payload)
+            return
+        if id_ == b"DONE":
+            # push 文件结束（8B 无 payload，length 字段=mtime）
+            if self.expecting == "data_c":
+                mtime = struct.unpack_from("<I", frame, 4)[0]
+                # P4: DONE 时取解压器尾部字节一并写盘（sendall 原样透传不受影响）
+                self._flush_decoder()
+                self.logger.event(
+                    f"[sync push done]: {self.basename} size={self.accumulated} mtime={mtime}"
+                )
+                # rename 在 _close_capture 内完成（临时名 -> {stem}-{accumulated}-{mtime}{ext}），
+                # 必须在 _reset_file_state 之前（此时 basename/accumulated 仍非 None）
+                self._close_capture(mtime=mtime)
+                self._reset_file_state()
+            return
+        if id_ == b"QUIT":
+            self._close_capture()
+            self.expecting = None
+            return
+        if id_ == b"FAIL":
+            msglen = struct.unpack_from("<I", frame, 4)[0]
+            msg = frame[8 : 8 + msglen].decode("utf-8", errors="ignore")
+            self.logger.event(f"[sync client FAIL]: {msg!r}")
+            return
+
+    def _on_server_frame(self, id_, frame):
+        if id_ in (b"STA2", b"LST2"):
+            # sync_stat_v2(72B)：id,error,dev,ino,mode,nlink,uid,gid,size,atime,mtime,ctime
+            fields = struct.unpack(_STAT_V2_FMT, frame[:_STAT_V2_SIZE])
+            _id, error, _dev, _ino, _mode, _nlink, _uid, _gid, size, _at, _mt, _ct = (
+                fields
+            )
+            # pull 必先发 STAT_V2（AOSP file_sync_client.cpp:1008 sync_stat），proxy 在 RECV 前可见 size
+            # 命名用：pull 文件名 size 段取此字段；mtime(_mt) 不取（pull 用 python ts）
+            self.remote_size = size
+            self.logger.debug(f"[sync {id_.decode()} resp]: error={error} size={size}")
+            return
+        if id_ == b"STAT":
+            # sync_stat_v1(16B)
+            _id, mode, size, mtime = struct.unpack("<IIII", frame[:_STAT_V1_SIZE])
+            # pull 的 v1 stat 响应：同样存 size 供命名；mtime 不取
+            self.remote_size = size
+            self.logger.debug(
+                f"[sync lstat_v1 resp]: mode={mode} size={size} mtime={mtime}"
+            )
+            return
+        if id_ in (b"DNT2", b"DENT"):
+            # dent 头 + namelen 字节 name，目录项查询无文件落盘语义
+            if id_ == b"DNT2":
+                fields = struct.unpack(_DENT_V2_FMT, frame[:_DENT_V2_SIZE])
+                namelen = fields[-1]
+                name = frame[_DENT_V2_SIZE : _DENT_V2_SIZE + namelen].decode(
+                    "utf-8", errors="ignore"
+                )
+            else:
+                _id, _mode, _size, _mt, namelen = struct.unpack(
+                    "<IIIII", frame[:_DENT_V1_SIZE]
+                )
+                name = frame[_DENT_V1_SIZE : _DENT_V1_SIZE + namelen].decode(
+                    "utf-8", errors="ignore"
+                )
+            self.logger.debug(f"[sync {id_.decode()}]: name={name}")
+            return
+        if id_ == b"DATA":
+            if self.expecting == "data_s":
+                size = struct.unpack_from("<I", frame, 4)[0]
+                payload = frame[8 : 8 + size]
+                # P4: 旁路解压后写盘 + accumulated 累加解压后长度（sendall 原样压缩字节已更早透传）
+                self._feed_data(payload)
+            return
+        if id_ == b"DONE":
+            # pull 文件结束（8B 无 payload，length=0）；list 流也以 DONE 收尾
+            if self.expecting == "data_s":
+                # P4: DONE 时取解压器尾部字节一并写盘（sendall 原样透传不受影响）
+                self._flush_decoder()
+                self.logger.event(
+                    f"[sync pull done]: {self.basename} size={self.accumulated}"
+                )
+                self._close_capture()
+                self._reset_file_state()
+            else:
+                self.logger.debug("[sync DONE (list/stat end)]")
+            return
+        if id_ == b"OKAY":
+            # push 成功确认（client 已发 DONE 后 server 回 OKAY，8B 无 payload）
+            if self.file_fp:
+                self._close_capture()
+            self.expecting = "req"
+            self.awaiting_details = None
+            return
+        if id_ == b"FAIL":
+            msglen = struct.unpack_from("<I", frame, 4)[0]
+            msg = frame[8 : 8 + msglen].decode("utf-8", errors="ignore")
+            self.logger.event(f"[sync FAIL]: {msg!r}")
+            self._close_capture()
+            self._reset_file_state()
+            return
+
+    def _start_push(self, remote, v2):
+        self.op = "SEND"
+        self.remote_path = remote
+        self.basename = os.path.basename(remote) or "sync_file"
+        self.accumulated = 0
+        self.capture_overflow = False
+        # P4 Major 3: 深度防御——每文件开头重置解压器，防 v2-zstd push 中途 QUIT 后同连接
+        # v1 SEND 喂过时 decompressobj（_setup_decoder 仅在 v2 details 帧时调用，v1 不调）
+        self.compression = None
+        self.decoder = None
+        self.decoder_lib_missing = False
+        self.decoder_fallback = None
+        self._open_capture()
+        cap = self.capture_path if self.capture_enabled else "<disabled>"
+        self.logger.event(f"📤 [sync push]: remote={remote} local_capture={cap}")
+        if v2:
+            # 双发：path 帧已收，下一帧是 sync_send_v2 details struct
+            self.awaiting_details = "send"
+            # expecting 保持（path 请求可能在 "req"/"idle"，details 帧后置 data_c）
+        else:
+            self.awaiting_details = None
+            self.expecting = "data_c"
+
+    def _start_pull(self, remote, v2):
+        self.op = "RECV"
+        self.remote_path = remote
+        self.basename = os.path.basename(remote) or "sync_file"
+        self.accumulated = 0
+        self.capture_overflow = False
+        # P4 Major 3: 深度防御——每文件开头重置解压器，防过时 decompressobj 串扰
+        self.compression = None
+        self.decoder = None
+        self.decoder_lib_missing = False
+        self.decoder_fallback = None
+        self._open_capture()
+        cap = self.capture_path if self.capture_enabled else "<disabled>"
+        self.logger.event(f"📥 [sync pull]: remote={remote} local_capture={cap}")
+        if v2:
+            self.awaiting_details = "recv"
+        else:
+            self.awaiting_details = None
+            self.expecting = "data_s"
+
+    # ----------------------------------------------------------------
+    # P4: sync v2 压缩旁路解压（仅作用于落盘 _write_capture，sendall 原样压缩字节透传）
+    # ----------------------------------------------------------------
+    def _setup_decoder(self, flags):
+        """按 sync v2 details flags 建流式解压器（旁路落盘用，sendall 原样压缩字节透传不变）。
+        flags & 4(kSyncFlagZstd) → zstandard；flags & 2 → lz4；flags & 1 → brotli。
+        import 失败/建库异常 → decoder_lib_missing 降级（原样落盘压缩字节 + warning）。"""
+        self.compression = None
+        self.decoder = None
+        self.decoder_lib_missing = False
+        self.decoder_fallback = None
+        compression_flags = flags & 0x7
+        if compression_flags & (compression_flags - 1):
+            self.logger.event(
+                f"[!] sync multiple compression flags: flags={flags}, degrading observer"
+            )
+            return False
+        if flags & 4:
+            self.compression = "zstd"
+            try:
+                import zstandard  # 环境硬依赖（.venv 已装），失败降级原样落盘 + warning
+
+                self.decoder = zstandard.ZstdDecompressor().decompressobj()
+            except Exception as e:
+                self.decoder_lib_missing = True
+                self.decoder_fallback = "unavailable"
+                self.logger.event(
+                    f"[!] sync 压缩库未装，落盘压缩字节（命名 size=压缩长度）: zstandard: {e}"
+                )
+        elif flags & 2:
+            self.compression = "lz4"
+            try:
+                import lz4.frame
+
+                self.decoder = lz4.frame.LZ4FrameDecompressor()
+            except Exception as e:
+                self.decoder_lib_missing = True
+                self.decoder_fallback = "unavailable"
+                self.logger.event(
+                    f"[!] sync 压缩库未装，落盘压缩字节（命名 size=压缩长度）: lz4: {e}"
+                )
+        elif flags & 1:
+            self.compression = "brotli"
+            try:
+                import brotli
+
+                self.decoder = brotli.Decompressor()
+            except Exception as e:
+                self.decoder_lib_missing = True
+                self.decoder_fallback = "unavailable"
+                self.logger.event(
+                    f"[!] sync 压缩库未装，落盘压缩字节（命名 size=压缩长度）: brotli: {e}"
+                )
+        # flags 无压缩位 → compression=None, decoder=None（DATA 原样落盘）
+        return True
+
+    def _feed_data(self, payload):
+        """DATA 帧旁路落盘：若已建流式解压器则先解压再写盘 + accumulated 累加解压后长度；
+        库未装/已异常降级 → 原样落盘压缩字节（size=压缩长度）；无压缩位 → 原样。
+        sendall 原样压缩字节透传（在更早已执行），此处仅旁路落盘。解压异常降级不阻断转发。
+        解压方法按库统一取：zstd/lz4 用 .decompress，brotli 用 .process（brotli.Decompressor 无 decompress）。"""
+        if self.decoder is not None:
+            try:
+                decompress = getattr(self.decoder, "decompress", None) or getattr(
+                    self.decoder, "process", None
+                )
+                payload = decompress(payload)
+            except Exception as e:
+                self.logger.event(f"[!] sync 解压异常，降级原样落盘: {e}")
+                self.decoder = None
+                self.decoder_lib_missing = True
+                self.decoder_fallback = "failed"
+        # decoder None（无压缩/库未装/异常降级）→ payload 原样；decoder 非空 → payload 已是解压后字节
+        self._write_capture(payload)
+        self.accumulated += len(payload)
+
+    def _flush_decoder(self):
+        """DONE 时取解压器尾部字节一并写盘（zstandard flush() 返回尾部，.eof 校验完成）。
+        lz4/brotli 无 flush 接口（decompress() 已返回全部），getattr 守卫跳过。
+        异常降级不阻断（sendall 原样透传已在更早执行）。"""
+        if self.decoder is None:
+            return
+        flush = getattr(self.decoder, "flush", None)
+        if flush is None:
+            return
+        try:
+            tail = flush()
+        except Exception as e:
+            self.logger.event(f"[!] sync 解压 flush 异常: {e}")
+            self.decoder_lib_missing = True
+            self.decoder_fallback = "failed"
+            return
+        if tail:
+            self._write_capture(tail)
+            self.accumulated += len(tail)
+
+    def _open_capture(self):
+        # 统一命名：sync-{stem}-conn{N}-{size}B-{time_ns}-{seq}{ext}
+        # - SEND(push)：临时名 …-tmp-…，DONE 后 _close_capture rename 为终名（含真实 accumulated）
+        # - RECV(pull)：终名直接用 STAT/STA2 size；极少数 stat 未到 → 0B
+        # stem sanitize 后最多 64 字符
+        if not self.capture_enabled:
+            self.capture_path = None
+            self.file_fp = None
+            return
+        try:
+            stem, ext = os.path.splitext(self.basename)
+            stem = re.sub(r"[^A-Za-z0-9._-]", "_", stem)[:64] or "sync_file"
+            stream_id = getattr(self.logger, "conn_id", "na")
+            if self.op == "SEND":
+                # push 临时名（不打 captured，DONE 后 rename 为终名）
+                prefix = f"sync-{stem}-conn{stream_id}-tmp"
+            else:
+                # pull 终名：size 取 STAT/STA2；未到则 0B（captured 仍报真实 accumulated）
+                size = self.remote_size if self.remote_size is not None else 0
+                prefix = f"sync-{stem}-conn{stream_id}-{size}B"
+            self.capture_path, self.file_fp = open_unique_capture(
+                self.files_dir, prefix, ext
+            )
+        except IOError as e:
+            self.logger.event(f"[!] capture open failed: {e}")
+            self.capture_path = None
+            self.file_fp = None
+            self.capture_overflow = True
+
+    def _write_capture(self, payload):
+        """流式写盘：每帧 payload 直接 write 到已 open file_fp。IOError 内化不冒泡。"""
+        if not self.file_fp or self.capture_overflow:
+            return
+        if self.accumulated + len(payload) > MAX_SYNC_FILE:
+            self.logger.event(
+                f"[!] sync file > {MAX_SYNC_FILE} bytes, stop capturing: {self.basename}"
+            )
+            self._close_capture()
+            self.capture_overflow = True
+            return
+        try:
+            self.file_fp.write(payload)
+        except IOError as e:
+            self.logger.event(f"[!] capture write failed: {e}")
+            self._close_capture()
+            self.capture_overflow = True
+
+    def _close_capture(self, mtime=None):
+        # mtime 仅 push DONE 传入（DONE length 字段），用于临时名 rename 为终名后打唯一 captured。
+        # pull/FAIL/QUIT/overflow/teardown 均传 None：
+        #   - pull DONE：终名已在 _open_capture 定，直接打 captured（size=accumulated）
+        #   - push 未到 DONE（FAIL/QUIT/overflow/teardown）：file_fp 可能仍非 None → 守卫放行 close 但不打 captured（临时名不打 captured）
+        #   - 二次 close（DONE 后 OKAY）：file_fp 已 None → 守卫 return，不重复 captured
+        # 守卫：--no-capture / disabled / overflow 已 close / post-DONE OKAY 路径，避免 os.replace(None) TypeError
+        if not self.file_fp:
+            return
+        try:
+            self.file_fp.close()
+        except Exception:
+            pass
+        self.file_fp = None
+        if not (self.capture_enabled and self.capture_path):
+            return
+        cap_note = f" {self._capture_metadata()}"
+        # push 分支：DONE 后 rename 临时名 -> 终名 sync-{stem}-conn{N}-{accumulated}B-…，rename 后打 captured
+        if self.op == "SEND" and mtime is not None and self.basename:
+            try:
+                stem, ext = os.path.splitext(self.basename)
+                stem = re.sub(r"[^A-Za-z0-9._-]", "_", stem)[:64] or "sync_file"
+                stream_id = getattr(self.logger, "conn_id", "na")
+                final_path = reserve_unique_capture_path(
+                    self.files_dir,
+                    f"sync-{stem}-conn{stream_id}-{self.accumulated}B",
+                    ext,
+                )
+                source_path = self.capture_path
+                try:
+                    os.replace(source_path, final_path)
+                except Exception:
+                    try:
+                        os.unlink(final_path)
+                    except OSError:
+                        pass
+                    raise
+                self.capture_path = final_path  # 路径=最终权威
+            except Exception as e:
+                # rename 失败降级：保留临时名，不阻断转发（转发 sendall 在更早已执行）
+                self.logger.event(f"[!] sync rename failed: {e}")
+            self.logger.event(
+                f"[sync captured]: {self.capture_path} size={self.accumulated} mtime={mtime}{cap_note}"
+            )
+        elif self.op == "SEND":
+            # push 未到 DONE 就 close（overflow/FAIL/QUIT/teardown，mtime is None）：
+            # 临时名不打 captured（符合"只一条 captured 且路径为最终名"）。文件留临时名属降级。
+            return
+        else:
+            # pull 分支（op=="RECV"，mtime is None）：终名已在 _open_capture 定，打 captured（无 mtime）
+            self.logger.event(
+                f"[sync captured]: {self.capture_path} size={self.accumulated}{cap_note}"
+            )
+
+    def _reset_file_state(self):
+        """多文件：DONE/OKAY 后复位文件状态（frame_buf 保留余量，下一文件继续切帧）。"""
+        self.op = None
+        self.expecting = "idle"
+        self.awaiting_details = None
+        self.remote_path = None
+        self.basename = None
+        self.remote_size = None
+        self.accumulated = 0
+        self.capture_overflow = False
+        # P4: 每文件复位解压器（_start_* 已重置，此处兜底多文件 DONE/OKAY 后场景）
+        self.compression = None
+        self.decoder = None
+        self.decoder_lib_missing = False
+        self.decoder_fallback = None
+
+    def _capture_metadata(self):
+        """描述落盘内容格式，明确区分解码成功、缺失和中途失败。"""
+        if self.compression is None:
+            return "capture_format=raw compression=none decoder=not-needed"
+        if self.decoder_fallback == "unavailable":
+            return (
+                f"capture_format=wire-compressed compression={self.compression} "
+                "decoder=unavailable"
+            )
+        if self.decoder_fallback == "failed":
+            return (
+                f"capture_format=mixed compression={self.compression} decoder=failed"
+            )
+        return f"capture_format=decoded compression={self.compression} decoder=ok"
+
+    def close(self):
+        """连接关闭时兜底关闭未收完的文件（保留部分落盘便于排查）。"""
+        with self.lock:
+            self._close_capture()
+            self.expecting = None

adbproxy/protocols/__init__.py

@@ -0,0 +1 @@
+"""从参考脚本迁移而来的 ADB 线协议工具。"""

adbproxy/protocols/adb.py

@@ -0,0 +1,66 @@
+"""AdbProtocol facade: re-exports smart-socket + payload pure codecs.
+
+Appendix A symbols stay importable as ``AdbProtocol.<name>`` during Track 1.
+"""
+
+from __future__ import annotations
+
+from adbproxy.protocols.payload.install import (
+    is_install_stream_service as _is_install_stream_service,
+)
+from adbproxy.protocols.payload.install import (
+    parse_install_size as _parse_install_size,
+)
+from adbproxy.protocols.payload.shell_v2 import split_v2_frames as _split_v2_frames
+from adbproxy.protocols.smart_socket.classifier import ServiceClassifier
+from adbproxy.protocols.smart_socket.wire import format_service_frame as _format_service_frame
+
+
+class AdbProtocol:
+    """adb client↔server 协议解析工具，全部静态方法、无状态。"""
+
+    @staticmethod
+    def format_service_frame(service):
+        """编码 smart-socket ``<hex4><body>``，body 不得超过 0xffff 字节。"""
+        return _format_service_frame(service)
+
+    @staticmethod
+    def parse_service(svc):
+        """拆 service 串 -> (kind, args_set, cmd)。"""
+        return ServiceClassifier.parse_service(svc)
+
+    @staticmethod
+    def is_host_service(svc):
+        return ServiceClassifier.is_host_service(svc)
+
+    @staticmethod
+    def host_response_kind(svc):
+        """按 AOSP host service 选择响应 wire shape。"""
+        return ServiceClassifier.host_response_kind(svc)
+
+    @staticmethod
+    def is_shell_service(svc):
+        return ServiceClassifier.is_shell_service(svc)
+
+    @staticmethod
+    def is_sync_service(svc):
+        return ServiceClassifier.is_sync_service(svc)
+
+    @staticmethod
+    def is_install_stream_service(svc):
+        """判断是否为会发送 raw apk 字节的 install 流式服务。"""
+        return _is_install_stream_service(svc)
+
+    @staticmethod
+    def parse_install_size(svc):
+        """从 install 流式服务串提取 -S <size>。返回 int 或 None。"""
+        return _parse_install_size(svc)
+
+    @staticmethod
+    def split_v2_frames(buf):
+        """切分 v2 帧 [1B id][4B LE len][data]。
+
+        返回 (frames:list[(id,payload)], leftover:bytearray, ok:bool)。
+        ok=False 表示遇到非法 len，调用方应降级为碎片流。
+        """
+        return _split_v2_frames(buf)

adbproxy/protocols/payload/__init__.py

@@ -0,0 +1,17 @@
+"""Pure L3 payload codecs (shell_v2 / sync / install). No I/O."""
+
+from adbproxy.protocols.payload.install import (
+    is_install_stream_service,
+    parse_install_size,
+)
+from adbproxy.protocols.payload.shell_v2 import split_v2_frames
+from adbproxy.protocols.payload.sync import SyncFrame, SyncWireDecoder, plan_sync_frame
+
+__all__ = [
+    "SyncFrame",
+    "SyncWireDecoder",
+    "is_install_stream_service",
+    "parse_install_size",
+    "plan_sync_frame",
+    "split_v2_frames",
+]

adbproxy/protocols/payload/install.py

@@ -0,0 +1,44 @@
+"""Pure install stream service grammar (abb_exec package install / install-write)."""
+
+from __future__ import annotations
+
+import re
+
+# install 流式服务命中正则（核对 AOSP client/adb_install.cpp:208-243,637-643）：
+# 仅 package install / install-write 会发送 raw apk 字节；
+# install-create/install-commit/install-abandon 不发文件体，必须排除。
+# abb_exec: 服务的参数以 NULL 字节 \x00 作 ABB_ARG_DELIMETER（见 AOSP
+# client/commandline.h send_abb_exec_command），非空格分隔。故分隔符须
+# 同时匹配空白与 NULL：[\s\x00]。
+_INSTALL_BODY_RE = re.compile(r"[\s\x00]+install(?:-write)?(?:[\s\x00]|$)")
+_INSTALL_SIZE_RE = re.compile(r"-S[\s\x00]+(\d+)")
+
+
+def is_install_stream_service(svc: str | None) -> bool:
+    """判断是否为会发送 raw apk 字节的 install 流式服务。
+
+    命中：abb_exec:package install / install-write 且命令体含 -S <size>，
+    排除 install-create/install-commit/install-abandon（仅收发状态行，不发文件体）。
+    """
+    if svc is None or not svc.startswith("abb_exec:"):
+        return False
+    body = svc[len("abb_exec:") :]
+    if not body.startswith("package"):
+        return False
+    rest = body[len("package") :]
+    # 词边界匹配 install / install-write（install-create 因后续非空白/末尾被排除）
+    if not _INSTALL_BODY_RE.match(rest):
+        return False
+    # 显式排除不发文件体的控制命令（双保险）
+    for bad in ("install-create", "install-commit", "install-abandon"):
+        if bad in svc:
+            return False
+    return _INSTALL_SIZE_RE.search(svc) is not None
+
+
+def parse_install_size(svc: str | None) -> int | None:
+    """从 install 流式服务串提取 -S <size>。返回 int 或 None。"""
+    if not is_install_stream_service(svc):
+        return None
+    m = _INSTALL_SIZE_RE.search(svc)
+    return int(m.group(1)) if m else None