oep-client-python 0.0.1__py3-none-any.whl

oep_client/v1/hid_stream.py

@@ -0,0 +1,257 @@
+"""OEP over a vendor-defined USB HID interface (oep-spec oep-core §3): the way in when vendor bulk is not
+usable (no WinUSB / udev permission for raw USB), before a CDC port, which a probe may give to serial forwarding.
+
+Framing: every report carries count (u16 LE) and then that many bytes of the length-prefixed frame stream, the rest of
+the report zero. Report IDs are the HID transport's business, not OEP's: when the report descriptor declares one, every
+report on the wire starts with it - output reports too (EspUsbDevice takes a first byte equal to its report ID as the
+ID, so a report sent without it lost a byte whenever count's low byte matched).
+
+Backends, same shape as UsbBulkStream (read with a timeout, in_waiting, write, reset_input_buffer, close):
+  hidapi (`hid`, cython-hidapi): the OS HID driver - Windows, macOS, Linux hidraw. Needs no driver change on Windows.
+  libusb1 (`usb1`): detaches the kernel's HID driver and talks to the endpoints (Linux, raw USB permission).
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+VENDOR_USAGE_PAGE_MIN = 0xFF00
+
+
+def parse_report_descriptor(desc: bytes) -> list[dict]:
+    """The reports of a HID report descriptor: [{usage_page, report_id (0 = none), input, output}] with input/output in
+    bytes (the report ID not counted). Short items only (long items are skipped); enough for a vendor interface."""
+    reports: dict[tuple[int, int], dict] = {}
+    usage_page = report_id = size = count = 0
+    stack = []
+    i = 0
+    while i < len(desc):
+        prefix = desc[i]
+        if prefix == 0xFE:                               # long item: size in the next byte
+            i += 3 + (desc[i + 1] if i + 1 < len(desc) else 0)
+            continue
+        n = (0, 1, 2, 4)[prefix & 3]
+        value = int.from_bytes(desc[i + 1:i + 1 + n], "little")
+        tag, kind = prefix & 0xF0, prefix & 0x0C
+        i += 1 + n
+        if kind == 0x04:                                 # global
+            if tag == 0x00:
+                usage_page = value
+            elif tag == 0x70:
+                size = value
+            elif tag == 0x80:
+                report_id = value
+            elif tag == 0x90:
+                count = value
+            elif tag == 0xA0:
+                stack.append((usage_page, report_id, size, count))
+            elif tag == 0xB0 and stack:
+                usage_page, report_id, size, count = stack.pop()
+        elif kind == 0x00 and tag in (0x80, 0x90):       # main: Input / Output
+            r = reports.setdefault((usage_page, report_id),
+                                   {"usage_page": usage_page, "report_id": report_id, "input": 0, "output": 0})
+            r["input" if tag == 0x80 else "output"] += (size * count + 7) // 8
+    return list(reports.values())
+
+
+def vendor_report(desc: bytes) -> dict | None:
+    """The vendor-page report carrying both directions, if the descriptor has one."""
+    for r in parse_report_descriptor(desc):
+        if r["usage_page"] >= VENDOR_USAGE_PAGE_MIN and r["input"] >= 3 and r["output"] >= 3:
+            return r
+    return None
+
+
+class HidReportStream:
+    """count(u16) + frame bytes per report over a backend that moves whole reports (payload without the report ID)."""
+
+    def __init__(self, backend, input_size: int, output_size: int):
+        self.backend = backend
+        self.input_size, self.output_size = input_size, output_size
+        self.timeout = 0.05
+        self._buffer = bytearray()
+        self._cond = threading.Condition()
+        self._closed = False
+        self._reader = threading.Thread(target=self._drain, daemon=True)
+        self._reader.start()
+
+    def _drain(self) -> None:
+        while not self._closed:
+            try:
+                report = self.backend.read_report(0.1)
+            except OSError:
+                if self._closed:
+                    return
+                time.sleep(0.01)
+                continue
+            if len(report) < 2:
+                continue
+            n = min(report[0] | report[1] << 8, len(report) - 2)
+            if n:
+                with self._cond:
+                    self._buffer += report[2:2 + n]
+                    self._cond.notify_all()
+
+    @property
+    def in_waiting(self) -> int:
+        with self._cond:
+            return len(self._buffer)
+
+    def read(self, n: int = 1) -> bytes:
+        deadline = time.monotonic() + (self.timeout or 0)
+        with self._cond:
+            while not self._buffer:
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    return b""
+                self._cond.wait(left)
+            out = bytes(self._buffer[:n])
+            del self._buffer[:n]
+            return out
+
+    def write(self, data: bytes) -> int:
+        room = self.output_size - 2
+        for i in range(0, len(data), room):
+            part = data[i:i + room]
+            self.backend.write_report(len(part).to_bytes(2, "little") + part + bytes(room - len(part)))
+        return len(data)
+
+    def reset_input_buffer(self) -> None:
+        with self._cond:
+            self._buffer.clear()
+
+    def close(self) -> None:
+        self._closed = True
+        self._reader.join(timeout=0.5)
+        self.backend.close()
+
+
+class HidapiBackend:
+    def __init__(self, device, report_id: int):
+        self.device, self.report_id = device, report_id
+
+    def read_report(self, timeout: float) -> bytes:
+        data = bytes(self.device.read(65536, int(timeout * 1000)))
+        if data and self.report_id:
+            if data[0] != self.report_id:
+                return b""
+            data = data[1:]
+        return data
+
+    def write_report(self, payload: bytes) -> None:
+        # hidapi always takes the report ID first; 0 when the descriptor declares none (not sent on the wire)
+        if self.device.write(bytes([self.report_id]) + payload) < 0:
+            raise OSError("HID write failed")
+
+    def close(self) -> None:
+        self.device.close()
+
+
+class Usb1HidBackend:
+    def __init__(self, context, handle, interface: int, ep_in: int, ep_out: int | None, report_id: int, input_size: int):
+        import usb1
+        self._usb1 = usb1
+        self.context, self.handle, self.interface = context, handle, interface
+        self.ep_in, self.ep_out, self.report_id = ep_in, ep_out, report_id
+        self.in_len = input_size + (1 if report_id else 0)
+
+    def read_report(self, timeout: float) -> bytes:
+        try:
+            data = bytes(self.handle.interruptRead(self.ep_in, self.in_len, timeout=int(timeout * 1000)))
+        except self._usb1.USBErrorTimeout:
+            return b""
+        except self._usb1.USBError as e:
+            raise OSError(str(e)) from e
+        if data and self.report_id:
+            if data[0] != self.report_id:
+                return b""
+            data = data[1:]
+        return data
+
+    def write_report(self, payload: bytes) -> None:
+        wire = (bytes([self.report_id]) if self.report_id else b"") + payload
+        if self.ep_out is not None:
+            self.handle.interruptWrite(self.ep_out, wire, timeout=1000)
+        else:                                            # SET_REPORT (output) on the control pipe
+            self.handle.controlWrite(0x21, 0x09, 0x0200 | self.report_id, self.interface, wire, timeout=1000)
+
+    def close(self) -> None:
+        try:
+            self.handle.releaseInterface(self.interface)
+        finally:
+            self.handle.close()
+            self.context.close()
+
+
+def _open_hidapi(vid: int, pid: int, serial: str | None) -> HidReportStream:
+    import hid
+    for info in hid.enumerate(vid, pid):
+        if info.get("usage_page", 0) and info["usage_page"] < VENDOR_USAGE_PAGE_MIN:
+            continue
+        if serial and (info.get("serial_number") or "").lower() != serial.lower():
+            continue
+        dev = hid.device()
+        dev.open_path(info["path"])
+        try:
+            desc = bytes(dev.get_report_descriptor())
+        except (AttributeError, OSError):
+            dev.close()
+            continue
+        r = vendor_report(desc)
+        if r is None:
+            dev.close()
+            continue
+        return HidReportStream(HidapiBackend(dev, r["report_id"]), r["input"], r["output"])
+    raise FileNotFoundError(f"no vendor HID interface on {vid:04x}:{pid:04x}" + (f" serial {serial}" if serial else ""))
+
+
+def _open_usb1(vid: int, pid: int, serial: str | None) -> HidReportStream:
+    import usb1
+    context = usb1.USBContext()
+    context.open()
+    for dev in context.getDeviceIterator(skip_on_error=True):
+        if dev.getVendorID() != vid or dev.getProductID() != pid:
+            continue
+        handle = dev.open()
+        if serial and (handle.getSerialNumber() or "").lower() != serial.lower():
+            handle.close()
+            continue
+        for setting in dev.iterSettings():
+            if setting.getClass() != 3:
+                continue
+            number = setting.getNumber()
+            eps = [(e.getAddress(), e.getAttributes()) for e in setting]
+            ins = [a for a, attr in eps if attr & 3 == 3 and a & 0x80]
+            outs = [a for a, attr in eps if attr & 3 == 3 and not a & 0x80]
+            if not ins:
+                continue
+            # GET_DESCRIPTOR (report) on the interface
+            desc = bytes(handle.controlRead(0x81, 0x06, 0x2200, number, 4096, timeout=1000))
+            r = vendor_report(desc)
+            if r is None:
+                continue
+            if handle.kernelDriverActive(number):
+                handle.detachKernelDriver(number)
+            handle.claimInterface(number)
+            backend = Usb1HidBackend(context, handle, number, ins[0], outs[0] if outs else None, r["report_id"], r["input"])
+            return HidReportStream(backend, r["input"], r["output"])
+        handle.close()
+    context.close()
+    raise FileNotFoundError(f"no vendor HID interface on {vid:04x}:{pid:04x}" + (f" serial {serial}" if serial else ""))
+
+
+def open_hid(vid: int, pid: int, serial: str | None = None) -> HidReportStream:
+    """The probe's vendor HID interface: hidapi first (the OS driver, no permission beyond the HID node), then
+    libusb1."""
+    errors = []
+    for opener in (_open_hidapi, _open_usb1):
+        try:
+            return opener(vid, pid, serial)
+        except ImportError as e:
+            errors.append(f"{opener.__name__}: {e}")
+        except (OSError, FileNotFoundError) as e:
+            errors.append(f"{opener.__name__}: {e}")
+        except Exception as e:                           # usb1.USBError (access denied, busy) is not an OSError
+            errors.append(f"{opener.__name__}: {type(e).__name__}: {e}")
+    raise FileNotFoundError("; ".join(errors))

oep_client/v1/host.py

@@ -0,0 +1,321 @@
+"""Host side of the v1 session rules, over any `send(request bytes) -> result bytes` transport.
+
+The host picks a random u32 session id for every open (never a counter: after a probe reboot a counter would
+start again and match an old process's id). A one-shot CLI keeps the id between commands; a request that goes
+through with the same id proves nobody else operated the probe in between (oep-spec session-and-exclusivity).
+
+oep-core §4.1: role 0x81 (a session id in the header) goes only to a probe whose confirm answered revision 1 or more; a
+v0 probe drops the unknown role without an answer. The host confirms before its first open or session request.
+§3: when the probe's boot_id changes (open, heartbeat), or a probe with boot_id 0 answers no session, every
+connection and the plan are gone: `epoch` counts those losses, so a client holding a connection can tell.
+"""
+
+from __future__ import annotations
+
+import random
+import struct
+from dataclasses import dataclass, field
+from typing import Callable
+
+from . import message as m
+from .message import OepError, ProtocolError, ShortPayload  # noqa: F401  (re-exported: callers use host.*)
+
+MIN_REVISION = MAX_REVISION = 1          # the v1 shapes this client speaks
+OWNER = 0x01                             # open's owner TLV, and the same tag after lock_state / rejected locked
+
+
+class Rejected(OepError):
+    """The probe refused the request (resolution rejected): unknown fn / op, malformed, unavailable, locked..."""
+
+    def __init__(self, result: m.Result):
+        super().__init__(result.describe())
+        self.result = result
+
+
+class Failed(OepError):
+    """The probe ran the request and it did not work (completed, outcome failed or partial), or answered with a
+    resolution or outcome this host does not know (a failure too, oep-core §2.4)."""
+
+    def __init__(self, result: m.Result | None, why: str = ""):
+        super().__init__(why or (result.describe() if result is not None else "failed"))
+        self.result = result
+
+
+class NotV1(OepError):
+    """The probe does not speak v1 (confirm answered revision 0, or refused the ranged confirm as malformed)."""
+
+
+class Locked(Rejected):
+    @property
+    def remaining_ms(self) -> int:
+        return struct.unpack("<I", self.result.payload[:4])[0]
+
+    @property
+    def owner(self) -> str | None:
+        """The holder's owner text, when its open gave one (oep-core §6.4)."""
+        value = m.Tail.parse(self.result.payload[4:]).get(OWNER)
+        return value.decode("utf-8", "replace") if value is not None else None
+
+    def __str__(self) -> str:
+        who = f" by {self.owner}" if self.owner else ""
+        return f"locked{who} ({self.remaining_ms} ms of its lease left)"
+
+
+class InUse(OepError):
+    """The lock stayed with another session: its holder kept its lease going (named when it gave an owner)."""
+
+
+class NoSession(Rejected):
+    pass
+
+
+class Busy(Rejected):
+    pass
+
+
+class NoConnection(Rejected):
+    """The probe does not know the connection (never attached, probe restarted, lost to a wire or target reset):
+    attach again."""
+
+
+class Unsupported(Rejected):
+    """A critical TLV (`tag`) or a fixed-part value (tag None) the probe cannot handle."""
+
+    @property
+    def tag(self) -> int | None:
+        return self.result.payload[0] if self.result.payload else None
+
+
+_REJECTS = {m.LOCKED: Locked, m.NO_SESSION: NoSession, m.BUSY: Busy, m.NO_CONNECTION: NoConnection,
+            m.UNSUPPORTED: Unsupported}
+
+
+def rejection(result: m.Result) -> Rejected:
+    return _REJECTS.get(result.detail, Rejected)(result)
+
+
+@dataclass
+class Opened:
+    lease_ms: int
+    boot_id: int
+    resumed: bool
+
+
+@dataclass
+class Host:
+    send: Callable[[bytes], bytes]
+    rng: random.Random = field(default_factory=random.SystemRandom)
+    session: int | None = None
+    # The link's pipelining (SerialLink.exchange bound to the probe's in-flight / window limits); None: one at a time.
+    exchange: Callable[[list[bytes]], list[bytes]] | None = None
+    revision: int | None = None            # confirm's answer; None until asked
+    limits: dict | None = None             # confirm's answer as a dict
+    epoch: int = 0                         # +1 whenever every connection and the plan are lost (§3)
+    subscriptions: set = field(default_factory=set)   # fns subscribed in this session (a resync stops them blind)
+    # Called with every capture segment read (capture.CaptureRecord): the hook a run recorder hangs on.
+    on_capture: list = field(default_factory=list)
+    _corr: int = 0
+    _fns: dict = field(default_factory=dict)   # interface name -> fn, valid until the probe reboots (boot_id)
+    _revisions: dict = field(default_factory=dict)   # fn -> interface revision from list
+    _boot_id: int | None = None
+
+    def next_corr(self) -> int:
+        self._corr = self._corr % 0xFFFF + 1
+        return self._corr
+
+    def call(self, fn: int, op: int, payload: bytes = b"", *, locked: bool = True) -> m.Result:
+        """request() that also raises Failed unless the probe says it worked: what every operation wants."""
+        r = self.request(fn, op, payload, locked=locked)
+        if not r.succeeded:
+            raise Failed(r)
+        return r
+
+    def _session_for(self, locked: bool) -> int | None:
+        if not locked or self.session is None:
+            return None
+        self.require_v1()
+        return self.session
+
+    def request(self, fn: int, op: int, payload: bytes = b"", *, locked: bool = True) -> m.Result:
+        """locked=True sends the session id (role 0x81) once a session is open; lock-free requests may leave it off.
+        Rejections raise; any other answer is returned (Result.succeeded / .ran say what it was)."""
+        req = m.Request(self.next_corr(), fn, op, payload, self._session_for(locked))
+        result = m.Result.unpack(self.send(req.pack()))
+        if result.corr != req.corr:
+            raise ProtocolError(f"result for correlation {result.corr}, expected {req.corr}")
+        if result.resolution == m.REJECTED:
+            self._rejected(result)
+            raise rejection(result)
+        return result
+
+    def _rejected(self, result: m.Result) -> None:
+        if result.detail == m.NO_SESSION:
+            self.subscriptions.clear()                  # the lock is gone, and the subscriptions with it
+            if self._boot_id == 0:
+                self._lost()                            # a probe that cannot tell its boots: assume it restarted
+
+    def _lost(self) -> None:
+        self.epoch += 1
+        self._fns.clear()                               # a rebooted probe may number its interfaces differently
+        self._revisions.clear()
+        self.subscriptions.clear()
+
+    def boot_id_seen(self, boot_id: int) -> None:
+        """A boot_id from an open result or a heartbeat: a change means the probe restarted (§3)."""
+        if self._boot_id is not None and boot_id != self._boot_id:
+            self._lost()
+        self._boot_id = boot_id
+
+    def pipeline(self, requests: list[tuple[int, int, bytes]], exchange: Callable[[list[bytes]], list[bytes]] | None = None,
+                 *, locked: bool = True) -> list[m.Result]:
+        """Several requests in flight (`exchange` keeps the probe's in-flight and window limits); results in
+        order, rejects NOT raised - the caller looks at each result. Without `exchange`, one at a time."""
+        session = self._session_for(locked)
+        reqs = [m.Request(self.next_corr(), fn, op, payload, session) for fn, op, payload in requests]
+        packed = [r.pack() for r in reqs]
+        exchange = exchange or self.exchange
+        replies = exchange(packed) if exchange else [self.send(p) for p in packed]
+        results = [m.Result.unpack(r) for r in replies]
+        for req, res in zip(reqs, results):
+            if res.corr != req.corr:
+                raise ProtocolError(f"result for correlation {res.corr}, expected {req.corr}")
+            if res.resolution == m.REJECTED:
+                self._rejected(res)
+        return results
+
+    def pipeline_calls(self, requests: list[tuple[int, int, bytes]], *, locked: bool = True) -> list[m.Result]:
+        """pipeline() for operations that must all work: raises at the first result that was not a success (the
+        probe ran every request in order anyway)."""
+        results = self.pipeline(requests, locked=locked)
+        for r in results:
+            if r.resolution == m.REJECTED:
+                raise rejection(r)
+            if not r.succeeded:
+                raise Failed(r)
+        return results
+
+    # ---- confirm (§5, §2) -----------------------------------------------------------------------
+    def confirm(self, min_rev: int = MIN_REVISION, max_rev: int = MAX_REVISION) -> dict:
+        """Ask for a revision in [min_rev, max_rev]. -> {"revision", "flags", "max_frame", "window", "max_inflight"}.
+        A v0 probe answers revision 0 in the v0 shape; one that refuses the ranged confirm as malformed is not v1
+        either (revision 0 is recorded and the rejection raised). No revision in the range: rejected unsupported."""
+        try:
+            r = self.request(m.CORE_FN, m.OP_CONFIRM, m.CONFIRM_REQUEST + bytes([min_rev, max_rev]), locked=False)
+        except Rejected as e:
+            if e.result.detail == m.MALFORMED:
+                self.revision = 0
+            raise
+        if not r.succeeded:
+            raise Failed(r)
+        rd = m.Reader(r.payload)
+        magic, revision = rd.bytes(4), rd.u8()
+        if magic != m.CONFIRM_RESULT:
+            raise ProtocolError(f"confirm answered magic {magic!r}")
+        if revision == 0:                                   # v0: max_frame(16) window(16) max_inflight(8) flags(8)
+            max_frame, window, inflight = rd.take("HHB")
+            flags = rd.u8() if rd.at < len(rd.data) else 0
+            tail = m.Tail()
+        else:
+            if not min_rev <= revision <= max_rev:
+                raise ProtocolError(f"confirm answered revision {revision}, outside the {min_rev}..{max_rev} asked")
+            flags, max_frame, window, inflight = rd.take("BHIB")
+            tail = rd.tail()
+        self.revision = revision
+        self.limits = {"magic": magic, "revision": revision, "flags": flags, "max_frame": max_frame, "window": window,
+                       "max_inflight": inflight, "tail": tail}
+        return self.limits
+
+    def confirmed(self) -> dict:
+        """confirm()'s answer, asked once per host."""
+        return self.limits if self.limits is not None else self.confirm()
+
+    def require_v1(self) -> None:
+        """Before anything in the v1 shapes (role 0x81, open): the probe must have confirmed revision >= 1."""
+        if self.revision is None:
+            try:
+                self.confirm()
+            except Rejected as e:
+                if self.revision == 0:
+                    raise NotV1("the probe refused the ranged confirm (malformed): not a v1 probe") from e
+                raise
+        if self.revision < 1:
+            raise NotV1(f"the probe speaks OEP revision {self.revision}; session requests need revision 1 or more")
+
+    # ---- session --------------------------------------------------------------------------------
+    def open(self, lease_ms: int = 0, *, force: bool = False, session: int | None = None,
+             owner: str | None = None) -> Opened:
+        """A new random id unless `session` is given (a one-shot CLI resuming its saved id). lease_ms 0 = the probe's
+        default; 1000..60000 are taken as asked. owner: who holds the lock (1-32 bytes), shown to other hosts."""
+        self.require_v1()
+        sid = session if session is not None else self.rng.randrange(1, 1 << 32)
+        tail = m.tlv(OWNER, owner.encode()[:32]) if owner else b""
+        r = self.request(m.CORE_FN, m.OP_OPEN, struct.pack("<IIB", sid, lease_ms, int(force)) + tail, locked=False)
+        if sid != self.session:
+            self.subscriptions.clear()
+        self.session = sid
+        lease, boot_id, resumed = m.Reader(r.payload).take("IIB")
+        self.boot_id_seen(boot_id)
+        if not resumed:
+            self.subscriptions.clear()
+        return Opened(lease, boot_id, bool(resumed))
+
+    def end(self) -> None:
+        self.request(m.CORE_FN, m.OP_END)
+        self.subscriptions.clear()
+
+    def keepalive(self) -> None:
+        self.request(m.CORE_FN, m.OP_KEEPALIVE)
+
+    def lock_state(self) -> tuple[bool, int]:
+        locked, remaining = m.Reader(self.request(m.CORE_FN, m.OP_LOCK_STATE, locked=False).payload).take("BI")
+        return bool(locked), remaining
+
+    def lock_owner(self) -> tuple[bool, int, str | None]:
+        """lock_state with the holder's owner text (None: it gave none)."""
+        p = self.request(m.CORE_FN, m.OP_LOCK_STATE, locked=False).payload
+        locked, remaining = m.Reader(p).take("BI")
+        value = m.Tail.parse(p[5:]).get(OWNER)
+        return bool(locked), remaining, value.decode("utf-8", "replace") if value is not None else None
+
+    def take(self, lease_ms: int = 3000, *, owner: str | None = None, only_way_in: bool = False,
+             wait_s: float = 5.0, force: bool = False) -> Opened:
+        """open() the way host guide §2 takes the lock. only_way_in: this link is the probe's only transport and a
+        serial port opened exclusively - whoever held the lock cannot be there any more, so it is taken by force at
+        once. Otherwise the holder's lease is waited out (up to wait_s); a holder that keeps it going raises InUse,
+        naming it. force: take it anyway (the user said so)."""
+        import time
+        if force or only_way_in:
+            return self.open(lease_ms, force=True, owner=owner)
+        deadline = time.monotonic() + wait_s
+        while True:
+            try:
+                return self.open(lease_ms, owner=owner)
+            except Locked as e:
+                left = deadline - time.monotonic()
+                if left <= 0 or e.remaining_ms / 1000 > left:
+                    who = e.owner or "another session"
+                    raise InUse(f"the probe is in use by {who} (lease {e.remaining_ms} ms left, kept going)") from e
+                time.sleep(min(left, e.remaining_ms / 1000 + 0.05))
+
+    # ---- notifications (§4.5) -------------------------------------------------------------------
+    def subscribe(self, fn: int, min_bytes: int = 0, max_delay_ms: int = 0) -> None:
+        """Events and data pushes from `fn` (fn 0: heartbeats every max_delay_ms, 0 = 1000 ms). Send when min_bytes are
+        ready or max_delay_ms after the first byte (0, 0: as soon as there is anything). Ends with the lock."""
+        self.call(m.CORE_FN, m.OP_SUBSCRIBE, struct.pack("<HHH", fn, min_bytes, max_delay_ms))
+        self.subscriptions.add(fn)
+
+    def unsubscribe(self, fn: int) -> None:
+        self.call(m.CORE_FN, m.OP_UNSUBSCRIBE, struct.pack("<H", fn))
+        self.subscriptions.discard(fn)
+
+    def blind_stop(self) -> list[bytes]:
+        """The requests a resync may send without confirming (§1): unsubscribe every subscription and end the session
+        - both harmless when run twice - for when pushes keep the input from going quiet."""
+        if self.session is None or not self.revision:
+            return []
+        out = [m.Request(self.next_corr(), m.CORE_FN, m.OP_UNSUBSCRIBE, struct.pack("<H", fn), self.session).pack()
+               for fn in sorted(self.subscriptions)]
+        out.append(m.Request(self.next_corr(), m.CORE_FN, m.OP_END, b"", self.session).pack())
+        self.subscriptions.clear()
+        return out
+