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,477 @@
1
+ import logging
2
+ import ssl
3
+ from collections.abc import Sequence
4
+ from email.utils import parsedate_to_datetime
5
+
6
+ import anyio
7
+ from httpx2 import (
8
+ AsyncBaseTransport,
9
+ Auth,
10
+ Request,
11
+ RequestNotRead,
12
+ Response,
13
+ Timeout,
14
+ )
15
+
16
+ from .auth import BearerAuth
17
+ from .base import STREAMING_REQUEST_EXTENSION
18
+ from .calendar import CalendarClient
19
+ from .collectives import CollectivesClient
20
+ from .contacts import ContactsClient
21
+ from .cookbook import CookbookClient
22
+ from .deck import DeckClient
23
+ from .groups import GroupsClient
24
+ from .http import nextcloud_httpx_client, nextcloud_httpx_transport
25
+ from .mail import MailClient
26
+ from .news import NewsClient
27
+ from .notes import NotesClient
28
+ from .notes_search import NotesSearchController
29
+ from .ocs import OCS_REQUEST_HEADERS
30
+ from .sharing import SharingClient
31
+ from .shopping_list import ShoppingListClient
32
+ from .tables import TablesClient
33
+ from .talk import TalkClient
34
+ from .users import UsersClient
35
+ from .webdav import WebDAVClient
36
+
37
+ logger = logging.getLogger(__name__)
38
+
39
+
40
+ async def log_request(request: Request) -> None:
41
+ """Log the outgoing request at DEBUG, without touching a streamed body.
42
+
43
+ httpx2 only buffers a request body up front when it is given as bytes, str,
44
+ form data or JSON. For a streamed body (an async iterable, or multipart
45
+ ``files=``) ``request.content`` raises ``RequestNotRead`` instead. It used
46
+ to be evaluated as a log argument even with DEBUG off, so any such request
47
+ on the shared client would fail in this hook before it was sent.
48
+ """
49
+ if not logger.isEnabledFor(logging.DEBUG):
50
+ return
51
+ logger.debug(
52
+ "Request event hook: %s %s - Waiting for content",
53
+ request.method,
54
+ request.url,
55
+ )
56
+ try:
57
+ body: object = request.content
58
+ except RequestNotRead:
59
+ body = "<streaming; body not read>"
60
+ logger.debug("Request body: %s", body)
61
+ logger.debug("Headers: %s", request.headers)
62
+
63
+
64
+ async def log_response(response: Response):
65
+ """Log the response body at DEBUG, without ever consuming a streamed one.
66
+
67
+ Two bugs lived in the three lines this replaces, and together they defeated
68
+ the entire streamed-download path in production:
69
+
70
+ 1. ``aread()`` ran **unconditionally**, while only the logging was gated by
71
+ DEBUG. Every response in the app was therefore fully buffered and
72
+ stringified regardless of log level, purely to serve a line nobody saw.
73
+ 2. httpx2 invokes response hooks BEFORE the body is fetched, so on a streamed
74
+ GET that ``aread()`` pulled the whole document into memory and left the
75
+ caller's ``aiter_bytes()`` loop with nothing to stream. A 1 GB ingest
76
+ download became a 1 GB buffer plus its decoded ``.text`` copy -- ~3.6x the
77
+ file size resident -- which OOMKilled the fast-tier ingest workers.
78
+
79
+ So: bail out before the read when DEBUG is off, and never read a request the
80
+ caller marked as streaming.
81
+ """
82
+ if not logger.isEnabledFor(logging.DEBUG):
83
+ return
84
+ if response.request.extensions.get(STREAMING_REQUEST_EXTENSION):
85
+ # Reading here would consume the stream the caller is about to iterate.
86
+ logger.debug("Response [%s] <streaming; body not read>", response.status_code)
87
+ return
88
+ await response.aread()
89
+ logger.debug("Response [%s] %s", response.status_code, response.text)
90
+
91
+
92
+ def _as_mime_tuple(value: str | Sequence[str] | None) -> tuple[str, ...]:
93
+ """Normalise one-or-many MIME types to a tuple.
94
+
95
+ A tuple specifically: it is passed straight to ``str.startswith``, which
96
+ accepts a tuple of prefixes and so does the OR for free. A bare string is
97
+ wrapped rather than iterated -- iterating it would match every file whose
98
+ content type starts with any single letter of the type.
99
+ """
100
+ # One return, so the varying length is plainly a collection rather than a
101
+ # record whose shape a caller might unpack (python:S8495).
102
+ if value is None:
103
+ types: Sequence[str] = ()
104
+ elif isinstance(value, str):
105
+ types = (value,)
106
+ else:
107
+ types = value
108
+ return tuple(types)
109
+
110
+
111
+ def _normalise_search_result(item: dict) -> dict:
112
+ """Normalise a webdav.search_files item to the get_files_by_tag shape."""
113
+ path = item.get("path", "")
114
+ if path and not path.startswith("/"):
115
+ path = "/" + path
116
+
117
+ last_modified_timestamp = item.get("last_modified_timestamp")
118
+ last_modified = item.get("last_modified")
119
+ if last_modified_timestamp is None and last_modified:
120
+ try:
121
+ last_modified_timestamp = int(
122
+ parsedate_to_datetime(last_modified).timestamp()
123
+ )
124
+ except (TypeError, ValueError):
125
+ last_modified_timestamp = None
126
+
127
+ file_id = item.get("file_id") if item.get("file_id") is not None else item.get("id")
128
+
129
+ return {
130
+ "id": file_id,
131
+ "path": path,
132
+ "name": item.get("name") or (path.rsplit("/", 1)[-1] if path else ""),
133
+ "size": item.get("size", 0),
134
+ "content_type": item.get("content_type", ""),
135
+ "last_modified": last_modified,
136
+ "last_modified_timestamp": last_modified_timestamp,
137
+ "etag": item.get("etag"),
138
+ "is_directory": item.get("is_directory", False),
139
+ }
140
+
141
+
142
+ class AsyncDisableCookieTransport(AsyncBaseTransport):
143
+ """This Transport disable cookies from accumulating in the httpx2 AsyncClient
144
+
145
+ Thanks to: https://github.com/encode/httpx2/issues/2992#issuecomment-2133258994
146
+ """
147
+
148
+ def __init__(self, transport: AsyncBaseTransport):
149
+ self.transport = transport
150
+
151
+ async def handle_async_request(self, request: Request) -> Response:
152
+ response = await self.transport.handle_async_request(request)
153
+ response.headers.pop("set-cookie", None)
154
+ return response
155
+
156
+
157
+ class NextcloudClient:
158
+ """Main Nextcloud client that orchestrates all app clients."""
159
+
160
+ def __init__(
161
+ self,
162
+ base_url: str,
163
+ username: str,
164
+ auth: Auth | None = None,
165
+ *,
166
+ auth_username: str | None = None,
167
+ password: str | None = None,
168
+ token: str | None = None,
169
+ verify: bool | ssl.SSLContext = True,
170
+ keepalive: bool = True,
171
+ ):
172
+ # ``verify`` is httpx2's: False disables TLS verification, and an
173
+ # SSLContext carries a custom CA. ``keepalive=False`` opens a fresh
174
+ # connection per request (see ``http.nextcloud_httpx_transport``).
175
+ #
176
+ # ``username`` is the Nextcloud UID and DAV path fallback. Discovery can
177
+ # replace that fallback with the canonical principal id when Nextcloud
178
+ # exposes a different DAV identity. ``auth_username`` is the credential
179
+ # identity Nextcloud authenticates the app password against (the
180
+ # loginName), which differs from the UID for OIDC-provisioned users.
181
+ # Defaults to ``username`` so single-user and OAuth modes are unchanged.
182
+ # Callers pass the matching ``auth=BasicAuth(auth_username, ...)`` for
183
+ # the httpx2 leg; ``auth_username`` is threaded to the CalDAV client,
184
+ # which builds its own auth object from the raw credential.
185
+ self.username = username
186
+ auth_username = auth_username or username
187
+ self._client = nextcloud_httpx_client(
188
+ base_url=base_url,
189
+ auth=auth,
190
+ verify=verify,
191
+ transport=AsyncDisableCookieTransport(
192
+ nextcloud_httpx_transport(verify=verify, keepalive=keepalive)
193
+ ),
194
+ event_hooks={"request": [log_request], "response": [log_response]},
195
+ timeout=Timeout(timeout=30, connect=5),
196
+ )
197
+
198
+ # Initialize app clients
199
+ self.notes = NotesClient(self._client, username)
200
+ self.webdav = WebDAVClient(self._client, username)
201
+ self.tables = TablesClient(self._client, username)
202
+ # CalendarClient takes raw credentials so caldav (which uses niquests as
203
+ # its preferred backend in v3.x) builds a backend-compatible auth object
204
+ # itself — passing httpx2.BasicAuth here breaks under niquests (#731).
205
+ self.calendar = CalendarClient(
206
+ base_url,
207
+ username,
208
+ auth_username=auth_username,
209
+ password=password,
210
+ token=token,
211
+ verify=verify,
212
+ )
213
+ self.contacts = ContactsClient(self._client, username)
214
+ self.cookbook = CookbookClient(self._client, username)
215
+ self.collectives = CollectivesClient(self._client, username)
216
+ self.deck = DeckClient(self._client, username)
217
+ self.news = NewsClient(self._client, username)
218
+ self.mail = MailClient(self._client, username)
219
+ self.talk = TalkClient(self._client, username)
220
+ self.users = UsersClient(self._client, username)
221
+ self.groups = GroupsClient(self._client, username)
222
+ self.sharing = SharingClient(self._client, username)
223
+ self.shopping_list = ShoppingListClient(self._client, username)
224
+
225
+ # Initialize controllers
226
+ self._notes_search = NotesSearchController()
227
+
228
+ @classmethod
229
+ def from_token(
230
+ cls,
231
+ base_url: str,
232
+ token: str,
233
+ username: str,
234
+ *,
235
+ verify: bool | ssl.SSLContext = True,
236
+ keepalive: bool = True,
237
+ ):
238
+ """Create NextcloudClient with OAuth bearer token.
239
+
240
+ Args:
241
+ base_url: Nextcloud base URL
242
+ token: OAuth access token
243
+ username: Nextcloud username
244
+ verify: TLS verification, as for ``__init__``
245
+ keepalive: Connection reuse, as for ``__init__``
246
+
247
+ Returns:
248
+ NextcloudClient configured with bearer token authentication
249
+ """
250
+ logger.info("Creating NC Client for user '%s' using OAuth token", username)
251
+ return cls(
252
+ base_url=base_url,
253
+ username=username,
254
+ auth=BearerAuth(token),
255
+ token=token,
256
+ verify=verify,
257
+ keepalive=keepalive,
258
+ )
259
+
260
+ async def capabilities(self):
261
+ response = await self._client.get(
262
+ "/ocs/v2.php/cloud/capabilities",
263
+ headers=dict(OCS_REQUEST_HEADERS),
264
+ )
265
+ response.raise_for_status()
266
+
267
+ return response.json()
268
+
269
+ async def get_enabled_apps(self) -> set[str]:
270
+ """Return the set of app ids enabled for the authenticated user.
271
+
272
+ Uses the per-user core navigation endpoint, which lists only apps the
273
+ current user can access (respecting group restrictions). The vector
274
+ scanner uses this to skip polling apps the user lacks, which would 404
275
+ and flood tenant logs. Preferred over ``/cloud/capabilities`` because
276
+ the News app advertises no capability and so never appears there.
277
+ """
278
+ response = await self._client.get(
279
+ "/ocs/v2.php/core/navigation/apps",
280
+ headers=dict(OCS_REQUEST_HEADERS),
281
+ )
282
+ response.raise_for_status()
283
+ data = response.json()
284
+ # ``X or {}``/``or []`` (not ``.get(k, default)``) so a present-but-null
285
+ # ``ocs``/``data`` (``{"ocs": null}``) coerces to empty instead of
286
+ # raising AttributeError on ``None.get``.
287
+ ocs = data.get("ocs") or {}
288
+ # A 200 carrying ``meta.status != "ok"`` is an OCS-level failure (auth /
289
+ # permission edge cases) that ``raise_for_status`` can't see. Raise so
290
+ # the scanner's ``_get_enabled_apps_or_none`` catches it and falls back
291
+ # to scanning every app, rather than silently gating all apps off for a
292
+ # cycle on an empty ``data``. Tolerate a missing/empty meta (our own
293
+ # mocks, and any envelope that omits it).
294
+ status = (ocs.get("meta") or {}).get("status")
295
+ if status and status != "ok": # falsy (missing/None/"") tolerated
296
+ raise ValueError(f"OCS navigation returned status={status!r}")
297
+ entries = ocs.get("data") or []
298
+ enabled: set[str] = set()
299
+ for entry in entries:
300
+ # ``app`` is the canonical app id; ``id`` matches it for the apps we
301
+ # gate. Union both so an unexpected nav-entry shape never hides an
302
+ # enabled app — a false "disabled" would skip real indexing.
303
+ for key in ("app", "id"):
304
+ value = entry.get(key)
305
+ if value:
306
+ enabled.add(value)
307
+ return enabled
308
+
309
+ async def notes_search_notes(self, *, query: str):
310
+ """Search notes using token-based matching with relevance ranking."""
311
+ all_notes = self.notes.get_all_notes()
312
+ return await self._notes_search.search_notes(all_notes, query)
313
+
314
+ async def _walk_tagged_dir(
315
+ self,
316
+ dir_path: str,
317
+ mime_types: tuple[str, ...],
318
+ tag_name: str,
319
+ ) -> tuple[list[dict], bool]:
320
+ """Descendants of ``dir_path`` matching any of ``mime_types``.
321
+
322
+ Nextcloud's SEARCH takes a single content type per query, so this is one
323
+ request per type -- issued concurrently rather than in sequence, or a
324
+ tagged folder would cost six sequential round-trips at the default type
325
+ list where it used to cost one, and discovery latency scales with the
326
+ number of tagged folders.
327
+
328
+ Returns the descendants found plus whether any type's walk failed; each
329
+ failure is logged per type, and ``find_files_by_tag`` turns any failure
330
+ into an error rather than a partial result.
331
+ """
332
+ results: list[list[dict]] = [[] for _ in mime_types]
333
+ failed = False
334
+
335
+ async def walk(index: int, mime_type: str) -> None:
336
+ nonlocal failed
337
+ try:
338
+ # find_all_by_type pages past Nextcloud's default ~100-result
339
+ # SEARCH page so every tagged-folder descendant is discovered;
340
+ # find_by_type would silently cap a large folder.
341
+ results[index] = await self.webdav.find_all_by_type(
342
+ mime_type, scope=dir_path
343
+ )
344
+ except Exception as e:
345
+ failed = True
346
+ logger.warning(
347
+ "Tag-based directory walk failed for %r (tag %r, mime %s): "
348
+ "%s. Files of that type under this folder will NOT be "
349
+ "indexed until the walk succeeds.",
350
+ dir_path,
351
+ tag_name,
352
+ mime_type,
353
+ e,
354
+ )
355
+
356
+ # Results are collected by index rather than appended, so the order does
357
+ # not depend on which request finished first -- discovery output stays
358
+ # deterministic for the same corpus.
359
+ async with anyio.create_task_group() as tg:
360
+ for index, mime_type in enumerate(mime_types):
361
+ tg.start_soon(walk, index, mime_type)
362
+
363
+ return [row for rows in results for row in rows], failed
364
+
365
+ async def find_files_by_tag(
366
+ self,
367
+ tag_name: str,
368
+ mime_type_filter: str | Sequence[str] | None = None,
369
+ ) -> list[dict]:
370
+ """Return files carrying ``tag_name``, expanding tagged folders into matching descendants when ``mime_type_filter`` is set.
371
+
372
+ ``mime_type_filter`` accepts one MIME type or several. Several are
373
+ OR-ed: a tagged folder is expanded once per type, because Nextcloud's
374
+ SEARCH takes a single content type per query.
375
+ """
376
+ mime_types = _as_mime_tuple(mime_type_filter)
377
+ tag = await self.webdav.get_tag_by_name(tag_name)
378
+ if not tag:
379
+ logger.debug("Tag %r not found, returning empty list", tag_name)
380
+ return []
381
+
382
+ items = await self.webdav.get_files_by_tag(tag["id"])
383
+ if not items:
384
+ logger.debug("No items found with tag %r", tag_name)
385
+ return []
386
+
387
+ logger.debug(
388
+ "Found %d directly-tagged item(s) with tag %r", len(items), tag_name
389
+ )
390
+
391
+ # Split into directly-tagged files vs tagged directories.
392
+ by_id: dict[int, dict] = {}
393
+ tagged_dirs: list[dict] = []
394
+ for item in items:
395
+ if item.get("is_directory"):
396
+ tagged_dirs.append(item)
397
+ continue
398
+ if mime_types and not item.get("content_type", "").startswith(mime_types):
399
+ continue
400
+ file_id = item.get("id")
401
+ if file_id is None:
402
+ continue
403
+ by_id[file_id] = item
404
+
405
+ # Expand each tagged directory into its descendant files matching
406
+ # the MIME filter. Skip when no MIME filter is set — see docstring.
407
+ if mime_types and tagged_dirs:
408
+ for dir_info in tagged_dirs:
409
+ dir_path = dir_info.get("path", "").strip("/")
410
+ descendants, walk_failed = await self._walk_tagged_dir(
411
+ dir_path, mime_types, tag_name
412
+ )
413
+ # Never return a short list as if complete: the scanner treats
414
+ # every indexed file missing from it as deleted (Deck #1373).
415
+ if walk_failed:
416
+ raise RuntimeError(
417
+ f"Tag {tag_name!r} discovery incomplete: walk of "
418
+ f"{dir_path!r} failed"
419
+ )
420
+
421
+ added = 0
422
+ for d in descendants:
423
+ if d.get("is_directory"):
424
+ continue
425
+ file_id = (
426
+ d.get("file_id")
427
+ if d.get("file_id") is not None
428
+ else d.get("id")
429
+ )
430
+ if file_id is None:
431
+ continue
432
+ if file_id in by_id:
433
+ # Directly-tagged entry already wins; keeps the
434
+ # canonical shape from get_files_by_tag.
435
+ continue
436
+ by_id[file_id] = _normalise_search_result(d)
437
+ added += 1
438
+
439
+ logger.debug(
440
+ "Tag %r: directory %r expanded to %d descendant %s file(s)",
441
+ tag_name,
442
+ dir_path,
443
+ added,
444
+ ", ".join(mime_types),
445
+ )
446
+
447
+ files = list(by_id.values())
448
+ if mime_types:
449
+ logger.info(
450
+ "Returning %d file(s) with tag %r (mime_type=%s, "
451
+ "%d directly-tagged folder(s) expanded)",
452
+ len(files),
453
+ tag_name,
454
+ ", ".join(mime_types),
455
+ len(tagged_dirs),
456
+ )
457
+ else:
458
+ logger.info("Returning %d file(s) with tag %r", len(files), tag_name)
459
+ return files
460
+
461
+ def _get_webdav_base_path(self) -> str:
462
+ """Helper to get the base WebDAV path for the authenticated user."""
463
+ return self.webdav._get_webdav_base_path()
464
+
465
+ async def __aenter__(self):
466
+ """Async context manager entry."""
467
+ return self
468
+
469
+ async def __aexit__(self, exc_type, exc_val, exc_tb):
470
+ """Async context manager exit - closes all clients."""
471
+ await self.close()
472
+ return False # Don't suppress exceptions
473
+
474
+ async def close(self):
475
+ """Close the HTTP client and CalDAV client."""
476
+ await self._client.aclose()
477
+ await self.calendar.close()
@@ -0,0 +1,34 @@
1
+ """Bearer token authentication for httpx2."""
2
+
3
+ from httpx2 import Auth, Request
4
+
5
+
6
+ class BearerAuth(Auth):
7
+ """
8
+ Bearer token authentication flow for httpx2.
9
+
10
+ This auth class adds the Authorization: Bearer <token> header
11
+ to all outgoing requests.
12
+ """
13
+
14
+ def __init__(self, token: str):
15
+ """
16
+ Initialize bearer authentication.
17
+
18
+ Args:
19
+ token: The bearer token to use for authentication
20
+ """
21
+ self.token = token
22
+
23
+ def auth_flow(self, request: Request):
24
+ """
25
+ Add Authorization header to the request.
26
+
27
+ Args:
28
+ request: The outgoing HTTP request
29
+
30
+ Yields:
31
+ The modified request with Authorization header
32
+ """
33
+ request.headers["Authorization"] = f"Bearer {self.token}"
34
+ yield request