fix: address PR #814 reviewer follow-ups

- gateway_client: guard token cache with a lazy anyio.Lock so concurrent
  embed calls share one M2M token request instead of racing
- status subscriber: distinguish idle fetch timeouts from real broker
  errors (log + 5s backoff) instead of swallowing all and spinning
- nats: warn when the bus URL uses unencrypted transport (non-tls://)
- collection_metadata: accept an optional shared httpx client, make TLS
  verify explicit, document the unauthenticated control-plane contract
- replace python -O-stripped asserts with explicit ValueError in the bus
  status builder and the api metadata source
- document why the nil-UUID sentinel point can't collide with content ids

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

nextcloud_mcp_server/vector/queue/nats.py

@@ -29,6 +29,22 @@ STREAM_NAME = "mcp"
 INGEST_SUBJECT_PREFIX = "mcp.ingest.requested"
 
 
+def warn_if_insecure_nats_url(url: str) -> None:
+    """Log a warning when the bus URL is not TLS-encrypted.
+
+    ``nats://`` (and ``ws://``) carry tenant document metadata in cleartext;
+    production deployments should use ``tls://`` (or ``wss://``). We connect
+    regardless — this is an operator alert, not a hard failure.
+    """
+    scheme = url.split("://", 1)[0].lower()
+    if scheme not in ("tls", "wss"):
+        logger.warning(
+            "NATS bus URL uses unencrypted transport (scheme=%s://); "
+            "use tls:// in production to protect document metadata in transit",
+            scheme,
+        )
+
+
 def _modified_at_rfc3339(modified_at: int) -> str:
     """DocumentTask.modified_at is an epoch int (0 for deletes)."""
     return datetime.fromtimestamp(int(modified_at), tz=timezone.utc).isoformat()
@@ -74,6 +90,7 @@ class NatsTaskProducer:
     ) -> NatsTaskProducer:
         import nats  # noqa: PLC0415  (lazy: optional dependency for external mode)
 
+        warn_if_insecure_nats_url(url)
         nc = await nats.connect(url)
         js = nc.jetstream()
         await cls._ensure_stream(js, num_replicas)

nextcloud_mcp_server/vector/queue/status.py

@@ -126,6 +126,9 @@ class NatsStatusSubscriber:
     ) -> NatsStatusSubscriber:
         import nats  # noqa: PLC0415
 
+        from .nats import warn_if_insecure_nats_url  # noqa: PLC0415
+
+        warn_if_insecure_nats_url(url)
         nc = await nats.connect(url)
         js = nc.jetstream()
         return cls(nc, js, tenant_id, store)
@@ -138,6 +141,7 @@ class NatsStatusSubscriber:
     ) -> None:
         """Durable pull-consumer loop. Requires a live broker (integration)."""
         import anyio  # noqa: PLC0415
+        import nats.errors  # noqa: PLC0415
 
         subject = f"mcp.document.*.{self.tenant_id}"
         sub = await self._js.pull_subscribe(
@@ -148,10 +152,17 @@ class NatsStatusSubscriber:
         while not shutdown_event.is_set():
             try:
                 msgs = await sub.fetch(batch=16, timeout=5)
+            except nats.errors.TimeoutError:
+                # Expected when idle: no messages within the fetch window. Loop
+                # straight back to re-check shutdown — no log, no extra sleep.
+                continue
             except Exception:
-                # fetch timeout when idle — brief pause before re-checking
-                # shutdown, avoiding a tight check-and-sleep spin on quiet tenants.
-                await anyio.sleep(0.1)
+                # Real broker error (disconnect, auth failure, stream deleted).
+                # Log it and back off so we don't hot-spin against a dead broker.
+                logger.warning(
+                    "NATS status subscriber fetch failed; retrying", exc_info=True
+                )
+                await anyio.sleep(5)
                 continue
             for msg in msgs:
                 self.handle_message(msg.subject, msg.data)