nextcloud-client 0.211.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,443 @@
1
+ """Base client for Nextcloud operations with shared authentication."""
2
+
3
+ import logging
4
+ import random
5
+ import time
6
+ import xml.etree.ElementTree as ET
7
+ from abc import ABC
8
+ from contextlib import asynccontextmanager
9
+ from functools import wraps
10
+ from urllib.parse import unquote
11
+
12
+ import anyio
13
+ from httpx2 import (
14
+ AsyncClient,
15
+ HTTPError,
16
+ HTTPStatusError,
17
+ RequestError,
18
+ Response,
19
+ codes,
20
+ )
21
+
22
+ from . import instrumentation
23
+ from .dav_errors import enrich_dav_error
24
+
25
+ #: Marks a request whose body the caller intends to consume incrementally.
26
+ #:
27
+ #: httpx2 runs response event hooks BEFORE the body is fetched, so a hook that
28
+ #: calls ``aread()`` pulls the whole body into memory and leaves nothing for the
29
+ #: caller's ``aiter_bytes()`` loop -- silently turning a streamed download into a
30
+ #: buffered one. ``log_response`` checks for this marker and skips reading.
31
+ STREAMING_REQUEST_EXTENSION = "nextcloud_mcp_streaming"
32
+
33
+ logger = logging.getLogger(__name__)
34
+
35
+
36
+ #: Attempts allowed for a rate-limited (429) call, and the fixed wait between
37
+ #: them. 429 means "slow down", so the wait is long and flat.
38
+ MAX_RETRIES = 5
39
+ RATE_LIMIT_BACKOFF_SECONDS = 5
40
+
41
+ #: Retries allowed for a lock-contended (423) call, and the base backoff.
42
+ #:
43
+ #: 423 is a different failure from 429 and wants a different policy. Nextcloud
44
+ #: raises ``OCP\Lock\LockedException`` when it cannot upgrade a shared lock to
45
+ #: an exclusive one. Observed in CI as a note create and a concurrent note
46
+ #: LIST both calling ``mkdir`` on the same Notes folder: each holds a shared
47
+ #: lock on the path and each wants to upgrade, so neither can.
48
+ #:
49
+ #: **The jitter is the load-bearing part, not the doubling.** With a fixed
50
+ #: schedule both callers -- they are both this client, since the vector-sync
51
+ #: scanner reads the same user's notes -- back off by the same amount and
52
+ #: retry at the same instant, so they re-collide on every attempt. That is not
53
+ #: a hypothesis: a CI run showed the two requests failing at four identical
54
+ #: timestamps in a row before the budget ran out. Randomising the wait
55
+ #: desynchronises them so one acquires the exclusive lock and the other
56
+ #: follows.
57
+ #:
58
+ #: The budget is deliberately small and the original 423 is re-raised once it
59
+ #: is spent: a lock held by a long upload or an open editing session is a real
60
+ #: refusal, and this must never turn one into an unbounded wait.
61
+ LOCK_MAX_RETRIES = 3
62
+ LOCK_BACKOFF_SECONDS = 0.5
63
+
64
+
65
+ def _lock_backoff(attempt: int) -> float:
66
+ """Jittered backoff for the *attempt*-th (1-based) lock retry.
67
+
68
+ Equal jitter: half the doubling schedule is fixed, half is random, so the
69
+ wait stays in ``[base * 2**(n-1) / 2, base * 2**(n-1)]``. Full jitter
70
+ (uniform from zero) would break lockstep too, but lets a retry fire almost
71
+ immediately, which is the opposite of what a contended lock needs.
72
+ """
73
+ ceiling = LOCK_BACKOFF_SECONDS * 2 ** (attempt - 1)
74
+ # The marker below silences python:S2245 (pseudorandom generator). Not a
75
+ # security decision: this only chooses how long to wait before retrying a
76
+ # file lock, and predictability costs nothing here.
77
+ #
78
+ # Bare, not parenthesised -- a rule id in parentheses makes Sonar reject
79
+ # the comment as malformed (python:S7632) and suppress nothing.
80
+ return ceiling / 2 + random.uniform(0, ceiling / 2) # NOSONAR
81
+
82
+
83
+ def retry_on_429(func):
84
+ """Retry the two Nextcloud responses that mean "not now" rather than "no".
85
+
86
+ The `func` is assumed to be a method that is similar to `httpx2.Client.get`,
87
+ and returns an `httpx2.Response` object.
88
+
89
+ * **429 Too Many Requests** -- the server is rate limiting. Waits
90
+ ``RATE_LIMIT_BACKOFF_SECONDS`` and retries, up to ``MAX_RETRIES``
91
+ attempts, then raises ``RuntimeError``.
92
+ * **423 Locked** -- another request holds a lock on the path. Retries
93
+ ``LOCK_MAX_RETRIES`` times with a short *jittered* backoff (see
94
+ :func:`_lock_backoff`), then re-raises the original ``HTTPStatusError``
95
+ so a genuinely locked resource still surfaces as 423 rather than as a
96
+ retry-exhausted error.
97
+
98
+ The two budgets are counted separately: a lock wait is not a rate-limit
99
+ attempt, and spending one on the other would make either failure arrive
100
+ early.
101
+
102
+ (The name predates the 423 handling and is kept because every client
103
+ imports it.)
104
+ """
105
+
106
+ @wraps(func)
107
+ async def wrapper(*args, **kwargs):
108
+ retries = 0
109
+ lock_retries = 0
110
+
111
+ while True:
112
+ try:
113
+ retries += 1
114
+ response = await func(*args, **kwargs)
115
+ break
116
+
117
+ except HTTPStatusError as e:
118
+ # If we get a '429 Client Error: Too Many Requests'
119
+ # error we wait a couple of seconds and do a retry
120
+ if e.response.status_code == codes.TOO_MANY_REQUESTS:
121
+ logger.warning(
122
+ "429 Client Error: Too Many Requests, Number of attempts: %s",
123
+ retries,
124
+ )
125
+ # Record retry metric (extract app name from args if available)
126
+ if len(args) > 0 and hasattr(args[0], "app_name"):
127
+ instrumentation.hooks.on_api_retry(
128
+ app=args[0].app_name, reason="429"
129
+ )
130
+ await anyio.sleep(RATE_LIMIT_BACKOFF_SECONDS)
131
+ # Sleep first, then give up: preserves the original
132
+ # accounting, where the last attempt also waited.
133
+ if retries >= MAX_RETRIES:
134
+ logger.warning("All API call retries failed")
135
+ raise RuntimeError(
136
+ f"Maximum number of retries ({MAX_RETRIES}) exceeded "
137
+ "without success"
138
+ ) from e
139
+ elif e.response.status_code == codes.LOCKED:
140
+ if lock_retries >= LOCK_MAX_RETRIES:
141
+ logger.warning(
142
+ "423 Locked persisted after %s retries: %s",
143
+ lock_retries,
144
+ e,
145
+ )
146
+ raise
147
+ lock_retries += 1
148
+ # A lock wait is not a rate-limit attempt.
149
+ retries -= 1
150
+ # One value, used by both the log line and the sleep. It
151
+ # is random, so recomputing it for the log would print a
152
+ # wait that never happened.
153
+ delay = _lock_backoff(lock_retries)
154
+ logger.warning(
155
+ "423 Locked, retrying in %.2fs (attempt %s of %s): %s",
156
+ delay,
157
+ lock_retries,
158
+ LOCK_MAX_RETRIES,
159
+ e,
160
+ )
161
+ if len(args) > 0 and hasattr(args[0], "app_name"):
162
+ instrumentation.hooks.on_api_retry(
163
+ app=args[0].app_name, reason="423"
164
+ )
165
+ await anyio.sleep(delay)
166
+ elif e.response.status_code == 404:
167
+ # 404 errors are often expected (e.g., checking if attachments exist)
168
+ # Log as debug instead of warning
169
+ logger.debug(
170
+ "HTTPStatusError %s: %s, Number of attempts: %s",
171
+ e.response.status_code,
172
+ e,
173
+ retries,
174
+ )
175
+ raise
176
+ else:
177
+ logger.warning(
178
+ "HTTPStatusError %s: %s, Number of attempts: %s",
179
+ e.response.status_code,
180
+ e,
181
+ retries,
182
+ )
183
+ raise
184
+ except RequestError as e:
185
+ logger.warning(
186
+ "RequestError %s: %s, Number of attempts: %s",
187
+ e.request.url,
188
+ e,
189
+ retries,
190
+ )
191
+ raise
192
+
193
+ return response
194
+
195
+ return wrapper
196
+
197
+
198
+ class BaseNextcloudClient(ABC):
199
+ """Base class for all Nextcloud app clients."""
200
+
201
+ # Subclasses should set this to identify the app for metrics/tracing
202
+ app_name: str = "unknown"
203
+
204
+ def __init__(self, http_client: AsyncClient, username: str):
205
+ """Initialize with shared HTTP client and username.
206
+
207
+ Args:
208
+ http_client: Authenticated AsyncClient instance
209
+ username: Nextcloud username for WebDAV operations
210
+ """
211
+ self._client = http_client
212
+ self.username = username
213
+ self._principal_id: str | None = None
214
+ self._principal_discovered = False
215
+
216
+ def _get_webdav_base_path(self) -> str:
217
+ """Helper to get the base WebDAV path for the authenticated user."""
218
+ return f"/remote.php/dav/files/{self._principal_or_username()}"
219
+
220
+ async def _ensure_principal_id(self) -> None:
221
+ """Discover the canonical DAV principal id via current-user-principal."""
222
+ if getattr(self, "_principal_discovered", False):
223
+ return
224
+
225
+ body = (
226
+ '<?xml version="1.0" encoding="utf-8"?>'
227
+ '<d:propfind xmlns:d="DAV:"><d:prop>'
228
+ "<d:current-user-principal/>"
229
+ "</d:prop></d:propfind>"
230
+ )
231
+
232
+ try:
233
+ response = await self._make_request(
234
+ "PROPFIND",
235
+ "/remote.php/dav/",
236
+ content=body,
237
+ headers={"Depth": "0", "Content-Type": "application/xml"},
238
+ )
239
+ root = ET.fromstring(response.content)
240
+ href = None
241
+ for element in root.iter():
242
+ if element.tag.split("}")[-1] != "current-user-principal":
243
+ continue
244
+ for child in element.iter():
245
+ if child.tag.split("}")[-1] == "href" and child.text:
246
+ href = child.text.strip()
247
+ break
248
+ if href:
249
+ break
250
+
251
+ if not href:
252
+ logger.warning(
253
+ "DAV principal discovery returned no href; using username path"
254
+ )
255
+ return
256
+
257
+ principal_id = unquote(href.rstrip("/").split("/")[-1])
258
+ if not principal_id:
259
+ logger.warning(
260
+ "DAV principal discovery returned an empty principal id; "
261
+ "using username path"
262
+ )
263
+ return
264
+
265
+ self._principal_id = principal_id
266
+ self._principal_discovered = True
267
+ except (HTTPError, ET.ParseError, ValueError) as e:
268
+ logger.warning("DAV principal discovery failed; using username path: %s", e)
269
+
270
+ def _principal_or_username(self) -> str:
271
+ """Return the discovered DAV principal id, falling back to username."""
272
+ return getattr(self, "_principal_id", None) or self.username
273
+
274
+ @staticmethod
275
+ def _resolve_url(url: str) -> str:
276
+ """Prefix bare ``/apps/...`` and ``/core/...`` paths with ``/index.php``.
277
+
278
+ Pretty URLs (URL rewriting that strips ``index.php``) are an opt-in
279
+ Nextcloud feature; without them, ``/apps/<app>/...`` returns 404 — see
280
+ issue #732. ``/index.php/apps/<app>/...`` is the universal entry point
281
+ and works on every Nextcloud install regardless of web-server config,
282
+ so we route all app-API calls through it. Core routes such as
283
+ ``/core/preview.png`` go through the same front controller and need the
284
+ same prefix. ``/remote.php/dav/...`` and ``/ocs/...`` have their own
285
+ dedicated entry points and are unaffected.
286
+ """
287
+ if url.startswith(("/apps/", "/core/")):
288
+ return "/index.php" + url
289
+ return url
290
+
291
+ @asynccontextmanager
292
+ async def _stream_request(self, method: str, url: str, **kwargs):
293
+ """Streaming sibling of :meth:`_make_request`, yielding an unread Response.
294
+
295
+ Shares ``_resolve_url``, tracing and the API-call metric, so a streamed
296
+ download is not a second, untraced transport path. The body is NOT read
297
+ here -- the caller consumes ``aiter_bytes()`` inside the ``async with``.
298
+
299
+ ``retry_on_429`` deliberately does not apply: it re-invokes a coroutine
300
+ that returns a fully-read Response, and a partially-consumed stream
301
+ cannot be replayed. Retry only the connect+status phase instead, before
302
+ any body byte is yielded; a mid-body failure surfaces as the retryable
303
+ transport error it already is.
304
+ """
305
+ url = self._resolve_url(url)
306
+ logger.debug("Making streaming %s request to %s", method, url)
307
+
308
+ # Tell the response event hook to keep its hands off this body. Without
309
+ # it, log_response's aread() consumes the whole document before the
310
+ # caller's aiter_bytes() loop runs -- the download is then buffered, not
311
+ # streamed, and peak memory scales with file size again.
312
+ stream_extensions = {
313
+ **kwargs.pop("extensions", {}),
314
+ STREAMING_REQUEST_EXTENSION: True,
315
+ }
316
+
317
+ max_retries = 5
318
+ for attempt in range(1, max_retries + 1):
319
+ start_time = time.time()
320
+ # Status is recorded in a finally so the request is metered however
321
+ # the block ends. Without that, a failure raised by the CALLER's body
322
+ # loop (OversizeDownload, or the short-read RemoteProtocolError) is
323
+ # neither an HTTPStatusError nor a normal return, so the request went
324
+ # entirely unrecorded on mcp_nextcloud_api_requests_total.
325
+ status_code = 0
326
+ try:
327
+ with instrumentation.hooks.trace_api_call(
328
+ app=self.app_name, method=method, path=url
329
+ ):
330
+ async with self._client.stream(
331
+ method, url, extensions=stream_extensions, **kwargs
332
+ ) as response:
333
+ status_code = response.status_code
334
+ # Raised inside the stream context so the connection is
335
+ # released before the 429 handler sleeps and retries.
336
+ response.raise_for_status()
337
+ yield response
338
+ return
339
+ except HTTPStatusError as e:
340
+ status_code = e.response.status_code
341
+ if status_code == codes.TOO_MANY_REQUESTS and attempt < max_retries:
342
+ logger.warning(
343
+ "429 Too Many Requests on streaming download, attempt %s",
344
+ attempt,
345
+ )
346
+ instrumentation.hooks.on_api_retry(app=self.app_name, reason="429")
347
+ await anyio.sleep(5)
348
+ continue
349
+ # Same typing as the buffered path. The body is unread here (the
350
+ # status is raised inside the stream context), so this degrades
351
+ # to status-only typing -- a 507 download still arrives as
352
+ # DavInsufficientStorage, just without the server's wording.
353
+ enriched = enrich_dav_error(e)
354
+ if enriched is not e:
355
+ raise enriched from e
356
+ raise
357
+ finally:
358
+ # A retried 429 is metered as its own attempt, matching how
359
+ # retry_on_429 accounts for the buffered path.
360
+ instrumentation.hooks.on_api_call(
361
+ app=self.app_name,
362
+ method=method,
363
+ status_code=status_code,
364
+ duration=time.time() - start_time,
365
+ )
366
+ raise RuntimeError(
367
+ f"Maximum number of retries ({max_retries}) exceeded without success"
368
+ )
369
+
370
+ @retry_on_429
371
+ async def _make_request(self, method: str, url: str, **kwargs) -> Response:
372
+ """Common request wrapper with logging, tracing, and error handling.
373
+
374
+ Args:
375
+ method: HTTP method
376
+ url: Request URL
377
+ **kwargs: Additional request parameters
378
+
379
+ Returns:
380
+ Response object
381
+ """
382
+ url = self._resolve_url(url)
383
+ logger.debug("Making %s request to %s", method, url)
384
+
385
+ # Start timer for metrics
386
+ start_time = time.time()
387
+ status_code = 0
388
+
389
+ try:
390
+ # Wrap request in trace span
391
+ with instrumentation.hooks.trace_api_call(
392
+ app=self.app_name,
393
+ method=method,
394
+ path=url,
395
+ ):
396
+ response = await self._client.request(method, url, **kwargs)
397
+ status_code = response.status_code
398
+ response.raise_for_status()
399
+
400
+ # Record successful API call metrics
401
+ duration = time.time() - start_time
402
+ instrumentation.hooks.on_api_call(
403
+ app=self.app_name,
404
+ method=method,
405
+ status_code=status_code,
406
+ duration=duration,
407
+ )
408
+
409
+ return response
410
+
411
+ except (HTTPStatusError, RequestError) as e:
412
+ # Record error metrics
413
+ if isinstance(e, HTTPStatusError):
414
+ status_code = e.response.status_code
415
+ else:
416
+ status_code = 0 # Connection error, no status code
417
+
418
+ duration = time.time() - start_time
419
+ instrumentation.hooks.on_api_call(
420
+ app=self.app_name,
421
+ method=method,
422
+ status_code=status_code,
423
+ duration=duration,
424
+ )
425
+
426
+ # Attach the server's own explanation before re-raising. DAV replies
427
+ # name the concrete failure in the body (Sabre s:exception/s:message)
428
+ # and 412/423/507 become distinguishable types. Non-DAV responses are
429
+ # returned unchanged, and the result still subclasses HTTPStatusError,
430
+ # so every existing handler -- including retry_on_429's status check
431
+ # around this method -- is unaffected.
432
+ if isinstance(e, HTTPStatusError):
433
+ enriched = enrich_dav_error(e)
434
+ # ``enrich_dav_error`` hands back the *same* object when there is
435
+ # no DAV document to add, and ``raise e from e`` would set
436
+ # ``e.__cause__ = e`` -- an exception caused by itself. Re-raise
437
+ # it plainly instead, so ``from`` always means a real wrapping.
438
+ if enriched is not e:
439
+ raise enriched from e
440
+ raise
441
+
442
+ # Re-raise the exception
443
+ raise