MouseTools 6.0.0rc2__tar.gz → 6.1.0__tar.gz

{mousetools-6.0.0rc2 → mousetools-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mousetools
-Version: 6.0.0rc2
+Version: 6.1.0
 Summary: An unofficial Python wrapper for Disney's API
 Author: Scott Caratozzolo
 License-Expression: MIT
@@ -11,15 +11,18 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: more-itertools>=10.7.0
-Requires-Dist: pycryptodome>=3.22.0
+Requires-Dist: pycryptodomex>=3.22.0
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: niquests[http3,utls]>=3.20.0
 Requires-Dist: tzdata>=2025.2
+Requires-Dist: typing-extensions>=4.5; python_version < "3.13"
 Requires-Dist: websockets>=13.0
 Dynamic: license-file
 

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/__init__.py

@@ -8,6 +8,7 @@ from mousetools.entities import (
     DISNEYLAND_RESORT,
     WALT_DISNEY_WORLD,
     Appearance,
+    ArrivalPrediction,
     Attraction,
     AudioTour,
     Avatar,
@@ -18,6 +19,7 @@ from mousetools.entities import (
     Coordinates,
     DailySchedule,
     Destination,
+    DestinationArrival,
     DiningEvent,
     DinnerShow,
     Entertainment,
@@ -35,6 +37,7 @@ from mousetools.entities import (
     MenuItem,
     MenuPrice,
     MerchandiseFacility,
+    NameParts,
     PartySizeStatus,
     PhotoPass,
     PointOfInterest,
@@ -51,7 +54,9 @@ from mousetools.entities import (
     Spa,
     ThemePark,
     Tour,
+    TransportArrivals,
     Transportation,
+    TransportService,
     WaitTime,
     WalkUpAvailability,
     WaterPark,
@@ -59,15 +64,31 @@ from mousetools.entities import (
     load_many,
 )
 from mousetools.enums import ChannelSource, DestinationShort, EntityType, ScheduleSource
-from mousetools.stream import CalendarEvent, ChangeEvent, FacilityStatusEvent, ForecastEvent, RawChange
+from mousetools.stream import (
+    ArrivalsEvent,
+    ArrivalsFilter,
+    CalendarEvent,
+    ChangeEvent,
+    CharacterEvent,
+    DiningFacilityStatusFilter,
+    DocId,
+    FacilityStatusEvent,
+    ForecastEvent,
+    NonDiningFacilityStatusFilter,
+    RawChange,
+    SubscriptionFilter,
+)
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("mousetools")
 logger.addHandler(logging.NullHandler())
 
 __all__ = [
     "DISNEYLAND_RESORT",
     "WALT_DISNEY_WORLD",
     "Appearance",
+    "ArrivalPrediction",
+    "ArrivalsEvent",
+    "ArrivalsFilter",
     "Attraction",
     "AudioTour",
     "Avatar",
@@ -77,14 +98,18 @@ __all__ = [
     "ChangeEvent",
     "ChannelSource",
     "Character",
+    "CharacterEvent",
     "Client",
     "ContainerEntity",
     "Coordinates",
     "DailySchedule",
     "Destination",
+    "DestinationArrival",
     "DestinationShort",
     "DiningEvent",
+    "DiningFacilityStatusFilter",
     "DinnerShow",
+    "DocId",
     "Entertainment",
     "EntertainmentVenue",
     "Entity",
@@ -103,6 +128,8 @@ __all__ = [
     "MenuItem",
     "MenuPrice",
     "MerchandiseFacility",
+    "NameParts",
+    "NonDiningFacilityStatusFilter",
     "PartySizeStatus",
     "PhotoPass",
     "PointOfInterest",
@@ -119,8 +146,11 @@ __all__ = [
     "SearchResponse",
     "SearchResult",
     "Spa",
+    "SubscriptionFilter",
     "ThemePark",
     "Tour",
+    "TransportArrivals",
+    "TransportService",
     "Transportation",
     "WaitTime",
     "WalkUpAvailability",

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/auth/public.py

@@ -1,4 +1,5 @@
 import asyncio
+import logging
 from collections.abc import Callable
 
 from mousetools._internal.auth.base import LEEWAY_SECONDS, epoch_now
@@ -6,6 +7,8 @@ from mousetools._internal.config import load_config
 from mousetools._internal.transport import Transport
 from mousetools.errors import AuthError
 
+logger = logging.getLogger("mousetools.network.auth")
+
 
 class PublicAuth:
     """Zero-config guest-token auth (assertion/public grant). The Client binds the
@@ -62,6 +65,7 @@ class PublicAuth:
         if self._transport is None:
             raise AuthError("PublicAuth used before bind(transport)")
         if self._token is not None and self._now() < self._expires_at - LEEWAY_SECONDS:
+            logger.debug("reusing cached public token, %.0fs of life left", self._expires_at - self._now())
             return self._token
         async with self._grant_lock:
             # Re-check inside the lock: a concurrent caller may have granted while
@@ -77,8 +81,10 @@ class PublicAuth:
                 if resp.status_code is None or resp.status_code >= 400:
                     raise AuthError(f"public token grant failed: {resp.status_code} from {self._token_url}")
                 body = resp.json()
+                expires_in = int(body["expires_in"])
                 self._token = body["access_token"]
-                self._expires_at = self._now() + int(body["expires_in"])
+                self._expires_at = self._now() + expires_in
+                logger.info("public token refreshed, expires in %.0fs", expires_in)
             return self._token
 
     async def headers(self) -> dict[str, str]:

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/config.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass
 from functools import lru_cache
 from importlib.resources import files
 
-from Crypto.Cipher import AES
+from Cryptodome.Cipher import AES
 
 # AES-GCM appends a 16-byte authentication tag to the ciphertext.
 _GCM_TAG_BYTES = 16

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/loaders.py

@@ -1,11 +1,14 @@
 """Generic DataLoader: coalesce per-tick key loads into batched fetches."""
 
 import asyncio
+import logging
 from collections.abc import Awaitable, Callable
 from typing import Generic, TypeVar
 
 from mousetools.errors import NotFound
 
+logger = logging.getLogger("mousetools.network.loaders")
+
 T = TypeVar("T")
 
 
@@ -27,6 +30,7 @@ class DataLoader(Generic[T]):
         batch_fetch: Callable[[list[str]], Awaitable[dict[str, T]]],
         *,
         max_batch: int = 100,
+        name: str | None = None,
     ) -> None:
         """Create a loader around a batch-fetch callable.
 
@@ -36,9 +40,13 @@ class DataLoader(Generic[T]):
             max_batch: The largest chunk of keys passed to `batch_fetch` in
                 one call; a tick's coalesced keys are split into chunks of
                 this size.
+            name: Identifies this loader in its log records. Without it,
+                several loaders batching concurrently emit indistinguishable
+                lines; optional so any construction site still works.
         """
         self._batch_fetch = batch_fetch
         self._max_batch = max_batch
+        self._name = name or "unnamed"
         self._pending: dict[str, asyncio.Future[T]] = {}
         self._flush_scheduled = False
         self._tasks: set[asyncio.Task[None]] = set()
@@ -83,6 +91,8 @@ class DataLoader(Generic[T]):
         """
         try:
             keys = list(batch)
+            chunks = (len(keys) + self._max_batch - 1) // self._max_batch
+            logger.debug("batch[%s]: %d key(s) in %d chunk(s)", self._name, len(keys), chunks)
             await asyncio.gather(
                 *(
                     self._resolve_chunk(keys[start : start + self._max_batch], batch)
@@ -112,6 +122,12 @@ class DataLoader(Generic[T]):
             # settled with the error (its awaiters re-raise it) -- narrowing would
             # leave futures hung forever on an unexpected type. `Exception` (not
             # BaseException) deliberately lets CancelledError propagate.
+            logger.debug(
+                "batch[%s]: chunk fetch failed (%s); settling %d future(s) with it",
+                self._name,
+                type(exc).__name__,
+                len(chunk),
+            )
             for k in chunk:
                 if not batch[k].done():
                     batch[k].set_exception(exc)

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/services/couchbase.py

@@ -15,7 +15,7 @@ from mousetools._internal.services.http import looks_like_bot_block
 from mousetools._internal.transport import Transport
 from mousetools.errors import AuthError, BotChallengeError, DisneyServerError, HTTPStatusError, RateLimited
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("mousetools.network.couchbase")
 
 _JSON_OBJECT = re.compile(r"\{.*\}", re.DOTALL)
 # Pull the boundary token out of a `multipart/related; boundary=...` Content-Type,
@@ -43,7 +43,7 @@ def _raise_for_status_code(code: int | None, url: str) -> None:
         HTTPStatusError: Any other status code of 400 or higher.
     """
     if code is None:
-        raise DisneyServerError(f"no response from {url}")
+        raise DisneyServerError(f"no response from {url}", url=url)
     if code < 400:
         return
     if code == 401:
@@ -54,7 +54,7 @@ def _raise_for_status_code(code: int | None, url: str) -> None:
     if code == 429:
         raise RateLimited(url)
     if code >= 500:
-        raise DisneyServerError(f"{code} from {url}")
+        raise DisneyServerError(f"{code} from {url}", status=code, url=url)
     raise HTTPStatusError(f"{code} from {url}", status=code, url=url)
 
 
@@ -278,6 +278,9 @@ async def bulk_get(
             (response-level or per-doc), including a per-doc error other than
             `"not_found"` (e.g. `"forbidden"`/`"unauthorized"`).
     """
+    # `base_url` is constant for the client's life, so it cannot tell two concurrent
+    # bulk_gets apart under HTTP/2 multiplexing -- name the ids instead, bounded.
+    logger.debug("bulk_get: requesting %d id(s): %s", len(channel_ids), channel_ids[:5])
     resp = await transport.request(
         "POST",
         f"{base_url}/_bulk_get",
@@ -305,10 +308,20 @@ async def bulk_get(
     unexplained = [cid for cid in channel_ids if cid not in out and cid not in reported_missing]
     if unexplained:
         logger.debug(
-            "_bulk_get: %d requested id(s) resolved to neither a doc nor a not_found: %s",
+            "bulk_get: %d requested id(s) resolved to neither a doc nor a not_found: %s",
             len(unexplained),
             unexplained[:5],
         )
+    absent = [cid for cid in channel_ids if cid not in out]
+    # Names the requested ids AND the absent ones: the former is what pairs this
+    # record with its opener under H2 multiplexing, the latter is the diagnosis.
+    logger.debug(
+        "bulk_get: %d of %d id(s) returned for %s; absent: %s",
+        len(out),
+        len(channel_ids),
+        channel_ids[:5],
+        absent[:5],
+    )
     return out
 
 

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/services/ids.py

@@ -1,6 +1,9 @@
 """Couchbase channel-id construction and entity-id parsing (pure string ops)."""
 
 from mousetools.enums import ChannelSource
+from mousetools.errors import InvalidFilterError
+
+DOCS_URL = "https://caratozzoloxyz.gitlab.io/public/MouseTools/guides/streaming/"
 
 _VERSION = "1_0"
 
@@ -11,6 +14,7 @@ SOURCE_MULTI_LANG: dict[str, bool] = {
     ChannelSource.TODAY: False,
     ChannelSource.CALENDAR: False,
     ChannelSource.CHARACTERS: False,
+    ChannelSource.ARRIVALS: False,
 }
 
 # The type-slug segment (e.g. `.attraction.`) is a SEPARATE axis from
@@ -35,6 +39,13 @@ SOURCE_HAS_TYPE_SLUG: dict[str, bool] = {
 # source is currently in both; keep it that way.
 SOURCE_ID_SUFFIX: dict[str, str] = {ChannelSource.CHARACTERS: ".en.us"}
 
+# Sources whose channel embeds a compound parent clause (`<id>;entityType=<T>`) BEFORE the
+# version token, shifting `1_0` from parts[2] to parts[3]. arrivals is keyed by resort:
+#   wdw.arrivals.<resortId>;entityType=resort.1_0.<busStopId>;entityType=bus-stop
+# DocId.parse skips one extra segment for these. Typed dict[str, bool] like its siblings --
+# DocId.parse looks it up with the raw parsed source string.
+SOURCE_PARENT_KEYED: dict[str, bool] = {ChannelSource.ARRIVALS: True}
+
 
 _TYPE_CLAUSE = ";entityType="
 
@@ -180,3 +191,78 @@ def parent_channel_id(dest: str, source: ChannelSource, *, multi_language: bool)
     if multi_language:
         parts.append("en_us")
     return ".".join(parts)
+
+
+# facilitystatus is the only source observed to fan out across two channels
+# (corpus-wide check, 2026-08-02); deliberately not a general mechanism.
+def dining_facility_status_channel_id(dest: str) -> str:
+    """The dining-only facilitystatus split channel id.
+
+    Every facilitystatus document declares the universal channel (`parent_channel_id`)
+    PLUS exactly one of the two split channels, so subscribing to this one is a strict
+    narrowing of it.
+
+    Args:
+        dest: The destination code (e.g. `"wdw"`).
+
+    Returns:
+        The channel id, e.g. `"wdw.diningfacilitystatus.1_0"`.
+    """
+    return f"{dest}.diningfacilitystatus.{_VERSION}"
+
+
+def nondining_facility_status_channel_id(dest: str) -> str:
+    """The non-dining facilitystatus split channel id.
+
+    Every facilitystatus document declares the universal channel (`parent_channel_id`)
+    PLUS exactly one of the two split channels, so subscribing to this one is a strict
+    narrowing of it.
+
+    Args:
+        dest: The destination code (e.g. `"wdw"`).
+
+    Returns:
+        The channel id, e.g. `"wdw.nondiningfacilitystatus.1_0"`.
+    """
+    return f"{dest}.nondiningfacilitystatus.{_VERSION}"
+
+
+def parent_keyed_channel_id(dest: str, source: ChannelSource, parent_id: str, parent_type: str) -> str:
+    """Build a channel id whose parent clause precedes the version token.
+
+    Convention: `{dest}.{source}.{parent_id};entityType={parent_type}.1_0`. Used by
+    the `SOURCE_PARENT_KEYED` sources (arrivals, keyed by resort). `parent_id` may
+    be bare or already carry its `;entityType=` clause, which must then AGREE with
+    `parent_type` -- both a blank `parent_id` and a disagreeing clause would
+    otherwise build a syntactically valid channel the gateway silently ignores
+    forever, per `SubscriptionFilter`'s rejection principle (verified-wrong input
+    raises).
+
+    Args:
+        dest: The destination code (e.g. `"wdw"`).
+        source: The `ChannelSource` (e.g. `ChannelSource.ARRIVALS`).
+        parent_id: The parent entity's id, bare or composed.
+        parent_type: The parent's entity-type value (e.g. `"resort"`).
+
+    Returns:
+        The parent-keyed channel id.
+
+    Raises:
+        InvalidFilterError: `parent_id` is blank/whitespace-only, or its existing
+            `;entityType=` clause disagrees with `parent_type`.
+    """
+    if not parent_id.strip():
+        msg = f"parent_id must not be blank. See {DOCS_URL}"
+        raise InvalidFilterError(msg)
+    if _TYPE_CLAUSE in parent_id:
+        clause_type = parent_id.split(_TYPE_CLAUSE, 1)[1]
+        if clause_type != parent_type:
+            msg = (
+                f"parent_id {parent_id!r} carries a conflicting entityType clause; "
+                f"expected {parent_type!r}. See {DOCS_URL}"
+            )
+            raise InvalidFilterError(msg)
+        composed = parent_id
+    else:
+        composed = f"{parent_id}{_TYPE_CLAUSE}{parent_type}"
+    return f"{dest}.{source}.{composed}.{_VERSION}"

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/stream/codec.py

@@ -6,10 +6,13 @@ uncompressed payload bytes sent in that direction (absent on ACK frames).
 Compression is per-frame through one shared raw-deflate stream per connection.
 """
 
+import logging
 import struct
 import zlib
 from dataclasses import dataclass
 
+logger = logging.getLogger("mousetools.stream.codec")
+
 MSG, RPY, ERR, ACKMSG, ACKRPY = 0, 1, 2, 4, 5
 TYPE_MASK = 0x07
 COMPRESSED = 0x08
@@ -185,8 +188,12 @@ class FrameDecoder:
         flags, pos = read_varint(raw, pos)
         mtype = flags & TYPE_MASK
         if mtype in {ACKMSG, ACKRPY}:
+            logger.debug("blip flow-control ack (msg_no=%d, no payload)", msg_no)
             return None  # flow-control acks carry no payload we consume in v1
         if len(raw) - pos < 4:
+            # R2: adds msg_no/byte-length the exception lacks. Still raises -- the running
+            # CRC/inflate state is cumulative, so only a full reconnect recovers from this.
+            logger.debug("undecodable blip frame (msg_no=%d, %d bytes): shorter than its CRC trailer", msg_no, len(raw))
             raise CodecError("frame shorter than its CRC trailer")
         chunk = raw[pos:-4]
         if flags & COMPRESSED:
@@ -194,6 +201,7 @@ class FrameDecoder:
         self._in_crc = zlib.crc32(chunk, self._in_crc)
         (expected,) = struct.unpack(">I", raw[-4:])
         if (self._in_crc & 0xFFFFFFFF) != expected:
+            logger.debug("undecodable blip frame (msg_no=%d, %d bytes): running CRC32 mismatch", msg_no, len(raw))
             raise CodecError("running CRC32 mismatch: corrupt or desynchronized frame")
         key = (mtype in {RPY, ERR}, msg_no)
         buf = self._pending.setdefault(key, bytearray())

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/stream/connection.py

@@ -7,8 +7,9 @@ queued) sequence. Yields `RawChange`s.
 
 import asyncio
 import contextlib
+import logging
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
-from typing import TYPE_CHECKING, Protocol, cast
+from typing import TYPE_CHECKING, Protocol, Self, cast
 
 import websockets
 
@@ -17,6 +18,8 @@ from mousetools._internal.stream.protocol import BlipProtocol, RawChange
 if TYPE_CHECKING:
     from websockets.typing import Subprotocol
 
+logger = logging.getLogger("mousetools.stream.connection")
+
 _SUBPROTOCOLS = ["BLIP_3+CBMobile_3", "BLIP_3+CBMobile_2"]
 _UA = "MouseTools/stream (CouchbaseLite-compatible)"
 
@@ -173,7 +176,7 @@ class BlipConnection:
         self._seed_since = since
         self._caught_up_fired = False
 
-    async def __aenter__(self) -> "BlipConnection":
+    async def __aenter__(self) -> Self:
         """Open the socket and start the receive loop.
 
         Returns:
@@ -194,8 +197,10 @@ class BlipConnection:
             with contextlib.suppress(asyncio.CancelledError, StreamError):
                 await self._task
         if self._ws is not None:
-            with contextlib.suppress(Exception):
+            try:
                 await self._ws.close()
+            except Exception as close_exc:  # noqa: BLE001 -- teardown must not mask the real error
+                logger.debug("error closing stream socket for %s: %s", self._url, close_exc)
 
     def __aiter__(self) -> AsyncIterator[RawChange]:
         """Iterate change records as they arrive.
@@ -239,7 +244,17 @@ class BlipConnection:
                 attempt = self._bump_attempt(attempt)
                 if attempt > self._max_retries:
                     raise StreamError(f"stream reconnect exhausted after {attempt} attempts") from exc
-                await asyncio.sleep(min(2**attempt, 30))
+                delay = min(2**attempt, 30)
+                logger.warning(
+                    "stream session on %s failed (%s: %s); reconnect %d/%d in %.0fs",
+                    self._url,
+                    type(exc).__name__,
+                    exc,
+                    attempt,
+                    self._max_retries,
+                    delay,
+                )
+                await asyncio.sleep(delay)
                 continue
             # `_session()` returned cleanly -- real `websockets` does this on a server
             # 1000/1001 close. Must back off exactly like the except path above: without
@@ -248,7 +263,15 @@ class BlipConnection:
             attempt = self._bump_attempt(attempt)
             if attempt > self._max_retries:
                 raise StreamError(f"stream reconnect exhausted after {attempt} attempts")
-            await asyncio.sleep(min(2**attempt, 30))
+            delay = min(2**attempt, 30)
+            logger.warning(
+                "stream on %s closed by server; reconnect %d/%d in %.0fs",
+                self._url,
+                attempt,
+                self._max_retries,
+                delay,
+            )
+            await asyncio.sleep(delay)
 
     def _bump_attempt(self, attempt: int) -> int:
         """Reset `attempt` on a healthy flap (this session delivered data), else bump it.
@@ -261,6 +284,7 @@ class BlipConnection:
             flap), else `attempt + 1`.
         """
         if self._progress:  # delivered data this session: treat as a healthy flap
+            logger.debug("stream on %s flapped after delivering data; attempt counter reset", self._url)
             return 1
         return attempt + 1
 
@@ -269,6 +293,7 @@ class BlipConnection:
         ws = await self._connector(self._url, headers, _SUBPROTOCOLS)
         self._ws = ws
         since = self._seed_since if (self._seed_since is not None and self._last_seq == "0") else self._last_seq
+        logger.debug("stream connected to %s (channels=%r, since=%s)", self._url, self._channels, since)
         proto = BlipProtocol(channels=self._channels, since=since, live_forward=self._live_forward)
         try:
             for frame in proto.start():
@@ -288,5 +313,7 @@ class BlipConnection:
                 # would spin forever without ever yielding to the event loop.
                 await asyncio.sleep(0)
         finally:
-            with contextlib.suppress(Exception):
+            try:
                 await ws.close()
+            except Exception as exc:  # noqa: BLE001 -- teardown must not mask the real error
+                logger.debug("error closing stream socket for %s: %s", self._url, exc)

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/stream/protocol.py

@@ -6,11 +6,16 @@ NoReply frame makes Sync Gateway close the connection).
 """
 
 import json
+import logging
 from dataclasses import dataclass, field
 
 from mousetools._internal.stream import codec
 
+logger = logging.getLogger("mousetools.stream.protocol")
+
 _CKPT_CLIENT = "mousetools-stream-v1"
+# Longest channel CSV rendered whole in a log record before it is summarised.
+_LABEL_MAX = 48
 # go-blip default order of magnitude; tune down if a live replay backfill stalls (see Task-9).
 _ACK_INTERVAL = 50_000
 
@@ -22,7 +27,7 @@ class RawChange:
     This is what `Subscription` yields when opened with `raw=True` (see
     `Client.stream`/`Client.subscribe`/`Destination.subscribe`/`Entity.stream`):
     every field the wire protocol carries, with no `ChangeEvent` parsing applied.
-    Split `doc_id` yourself via `mousetools.stream.events.parse_doc_id`, or use
+    Split `doc_id` yourself via `mousetools.stream.events.DocId.parse`, or use
     the default `raw=False` stream if you want that (and value-object extraction)
     done for you.
 
@@ -51,6 +56,29 @@ class ProtocolOutput:
     caught_up: bool = False
 
 
+def _label_for(channels: str) -> str:
+    """Build the short subscription identifier carried by this protocol's log records.
+
+    Args:
+        channels: The CSV of Sync Gateway channels this subscription filters to;
+            empty means the whole bucket.
+
+    Returns:
+        A bounded identifier: the CSV itself when short, else its first channel
+        plus a count of the rest.
+    """
+    if not channels:
+        return "all-channels"
+    if len(channels) <= _LABEL_MAX:
+        return channels
+    first, sep, rest = channels.partition(",")
+    # A single over-long channel has no comma, so `first` is the whole string and
+    # there is no "rest" to count -- truncate it rather than claiming a phantom peer.
+    if not sep:
+        return f"{first[:_LABEL_MAX]}..."
+    return f"{first}+{rest.count(',') + 1} more"
+
+
 class BlipProtocol:
     """Drives one continuous, live-forward pull subscription."""
 
@@ -65,6 +93,7 @@ class BlipProtocol:
                 backfill from `since` is exhausted (replay-only).
         """
         self._channels = channels
+        self._label = _label_for(channels)
         self._since = since
         self._live_forward = live_forward
         self._enc = codec.FrameEncoder()
@@ -79,6 +108,7 @@ class BlipProtocol:
     def _request(self, props: dict[str, str], body: bytes = b"") -> bytes:
         self._out_no += 1
         self._my_reqs[self._out_no] = props.get("Profile", "")
+        logger.debug("blip[%s] -> %s (msg_no=%d)", self._label, props.get("Profile", "?"), self._out_no)
         return self._enc.frame(codec.MSG, self._out_no, props, body)
 
     def start(self) -> list[bytes]:
@@ -141,6 +171,8 @@ class BlipProtocol:
             self._on_changes(msg, out)
         elif msg.mtype == codec.MSG and msg.props.get("Profile") == "rev":
             self._on_rev(msg, out)
+        if out.caught_up:
+            logger.debug("blip[%s] caught up: replay backfill drained", self._label)
         return out
 
     def _on_response(self, req: str, msg: codec.Message, out: ProtocolOutput) -> None:
@@ -159,6 +191,9 @@ class BlipProtocol:
         try:
             rows = json.loads(msg.body) if msg.body.strip() else []
         except ValueError:
+            logger.debug(
+                "blip[%s] dropping changes frame with an unparseable body (msg_no=%d)", self._label, msg.msg_no
+            )
             rows = []
         if not rows:
             if not self._caught_up:

{mousetools-6.0.0rc2 → mousetools-6.1.0}/mousetools/_internal/transport.py

@@ -1,4 +1,6 @@
 import asyncio
+import logging
+import time
 from collections.abc import Mapping
 from typing import Any
 
@@ -6,6 +8,8 @@ import niquests
 
 from mousetools.errors import TransportError
 
+logger = logging.getLogger("mousetools.network.transport")
+
 
 class Transport:
     """Async HTTP transport. The `utls` extra gives the session a Chrome
@@ -49,7 +53,13 @@ class Transport:
             TransportError: If the underlying HTTP client cannot complete the
                 request at all (dropped connection, timeout, too many redirects).
         """
+        if self._sema.locked():
+            # A saturated semaphore looks exactly like a hung request from the
+            # outside; say so rather than leaving a silent gap in the trace.
+            logger.debug("transport at concurrency limit; %s %s queued", method, url)
         async with self._sema:
+            logger.debug("-> %s %s", method, url)
+            started = time.monotonic()
             try:
                 resp = await self._session.request(
                     method,
@@ -70,6 +80,7 @@ class Transport:
                     await self._session.gather(resp)
             except niquests.exceptions.RequestException as exc:
                 raise TransportError(f"request to {url} failed: {exc}", url=url) from exc
+            logger.debug("<- %s %s %s (%.0f ms)", method, url, resp.status_code, (time.monotonic() - started) * 1000)
             return resp
 
     async def aclose(self) -> None: