NXPY-266: Align on user and group generated UID

nuxeo/client.py

@@ -2,7 +2,7 @@
 import atexit
 import json
 import logging
-from typing import Any, Dict, Optional, Tuple, Type, Union
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
 from warnings import warn
 
 import requests
@@ -88,6 +88,39 @@ class NuxeoClient(object):
     :param kwargs: kwargs passed to :func:`NuxeoClient.request`
     """
 
+    # Cache mapping username -> generated UID.
+    # Populated lazily on first encounter via resolve_uid / resolve_username.
+    userid_mapper = {}  # type: Dict[str, str]
+
+    # --- Known param keys that carry a username value in REQUESTS ---
+    # These keys, when found inside the ``params`` dict sent to the server
+    # (either as URL query parameters or inside the automation payload),
+    # contain a username string that must be translated to a generated UID.
+    _USERNAME_REQUEST_KEYS = frozenset({
+        "username",        # Document.AddPermission, User.Invite, …
+        "user",            # Document.RemovePermission, …
+        "users",           # bulk user references
+        "userId",          # Task queries, …
+        "actors",          # Task delegate / reassign (may be a list)
+        "delegatedActors",  # Task delegate (may be a list)
+    })
+
+    # --- Known response keys whose value is a username / list of usernames ---
+    # After the server starts returning generated UIDs in these fields, we
+    # translate them back to usernames so callers (e.g. Drive) see no change.
+    _USERNAME_RESPONSE_KEYS = frozenset({
+        "lockOwner",
+        "dc:lastContributor",
+        "dc:creator",
+        "dc:contributors",   # list of usernames
+        "lastContributor",   # filesystem-item style
+        "principalName",     # audit entries
+        "actors",            # task actors (list, prefixed "user:…")
+        "initiator",         # workflow initiator
+        "author",            # comment author
+        "creator",           # some simplified payloads
+    })
+
     def __init__(
         self,
         auth=None,  # type: AuthType
@@ -168,6 +201,134 @@ def disable_retry(self):
         self._session.mount("https://", TCPKeepAliveHTTPSAdapter())
         self._session.mount("http://", HTTPAdapter())
 
+    # ------------------------------------------------------------------
+    #  Username ↔ Generated-UID mapping
+    # ------------------------------------------------------------------
+
+    def _fetch_uid_for_username(self, username):
+        # type: (str) -> str
+        """
+        Call the server to obtain the generated UID for *username*.
+
+        .. note::
+            Dummy placeholder — returns a deterministic fake UID.
+            Replace the body once the actual server endpoint is known.
+        """
+        dummy_uid = f"uid-{username}"
+        logger.debug("_fetch_uid_for_username(%r) -> %r  [DUMMY]", username, dummy_uid)
+        return dummy_uid
+
+    def _fetch_username_for_uid(self, uid):
+        # type: (str) -> str
+        """
+        Call the server to obtain the username for a generated *uid*.
+
+        .. note::
+            Dummy placeholder — strips the ``uid-`` prefix.
+            Replace the body once the actual server endpoint is known.
+        """
+        dummy_username = uid.replace("uid-", "", 1) if uid.startswith("uid-") else uid
+        logger.debug("_fetch_username_for_uid(%r) -> %r  [DUMMY]", uid, dummy_username)
+        return dummy_username
+
+    def resolve_uid(self, username):
+        # type: (str) -> str
+        """Return the generated UID for *username*, using cache first."""
+        if username in self.userid_mapper:
+            return self.userid_mapper[username]
+
+        uid = self._fetch_uid_for_username(username)
+        self.userid_mapper[username] = uid
+        return uid
+
+    def resolve_username(self, uid):
+        # type: (str) -> str
+        """Return the username for a generated *uid*, using reverse cache first."""
+        for username, mapped_uid in self.userid_mapper.items():
+            if mapped_uid == uid:
+                return username
+
+        username = self._fetch_username_for_uid(uid)
+        self.userid_mapper[username] = uid
+        return username
+
+    # ------------------------------------------------------------------
+    #  Request / Response translation helpers
+    # ------------------------------------------------------------------
+
+    def _translate_request_params(self, params):
+        # type: (Dict[str, Any]) -> Dict[str, Any]
+        """
+        Scan *params* for known username-carrying keys and replace each
+        username value with its corresponding generated UID.
+
+        Returns a **new** dict — the original is never mutated.
+        """
+        if not params:
+            return params
+
+        translated = {}
+        for key, value in params.items():
+            if key not in self._USERNAME_REQUEST_KEYS:
+                translated[key] = value
+                continue
+
+            if isinstance(value, str):
+                translated[key] = self._translate_single_username_to_uid(value)
+            elif isinstance(value, list):
+                translated[key] = [
+                    self._translate_single_username_to_uid(v) if isinstance(v, str) else v
+                    for v in value
+                ]
+            else:
+                translated[key] = value
+        return translated
+
+    def _translate_single_username_to_uid(self, value):
+        # type: (str) -> str
+        """Translate a single username string to its UID.
+
+        Supports prefixed values like ``"user:john"``."""
+        if ":" in value:
+            prefix, name = value.split(":", 1)
+            return f"{prefix}:{self.resolve_uid(name)}"
+        return self.resolve_uid(value)
+
+    def _translate_response(self, data):
+        # type: (Any) -> Any
+        """
+        Recursively walk *data* (dict / list) and replace generated UIDs
+        with usernames in every field whose key is in
+        ``_USERNAME_RESPONSE_KEYS``.
+
+        Mutates in-place for efficiency.
+        """
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if key in self._USERNAME_RESPONSE_KEYS:
+                    data[key] = self._translate_uid_value_to_username(value)
+                elif isinstance(value, (dict, list)):
+                    self._translate_response(value)
+        elif isinstance(data, list):
+            for item in data:
+                if isinstance(item, (dict, list)):
+                    self._translate_response(item)
+        return data
+
+    def _translate_uid_value_to_username(self, value):
+        # type: (Any) -> Any
+        """Translate a single UID string (or list of UIDs) back to username(s).
+
+        Supports prefixed values like ``"user:uid-john"``."""
+        if isinstance(value, str):
+            if ":" in value:
+                prefix, uid_part = value.split(":", 1)
+                return f"{prefix}:{self.resolve_username(uid_part)}"
+            return self.resolve_username(value)
+        elif isinstance(value, list):
+            return [self._translate_uid_value_to_username(v) for v in value]
+        return value
+
     def query(
         self,
         query,  # type: str
@@ -249,8 +410,12 @@ def request(
 
         kwargs.update(self.client_kwargs)
 
+        # --- Translate URL query params (e.g. ?userId=alice) -----------
+        if "params" in kwargs and isinstance(kwargs["params"], dict):
+            kwargs["params"] = self._translate_request_params(kwargs["params"])
+
         # Set the default value to `object` to allow someone
-        # to set `timeout` to `None`.
+        # to set `default` to `None`.
         if kwargs.get("timeout", object) is object:
             kwargs["timeout"] = (TIMEOUT_CONNECT, TIMEOUT_READ)
 
@@ -343,6 +508,16 @@ def request(
             exc = None
             del exc
 
+        # --- Wrap response so .json() auto-translates UIDs → usernames ---
+        if isinstance(resp, requests.Response) and self.userid_mapper is not None:
+            _original_json = resp.json
+
+            def _translated_json(**kw):
+                data = _original_json(**kw)
+                return self._translate_response(data)
+
+            resp.json = _translated_json  # type: ignore[assignment]
+
         return resp
 
     def _check_headers_and_params_format(self, headers, params):

nuxeo/operations.py

@@ -1,7 +1,8 @@
 # coding: utf-8
+import logging
 from collections.abc import Sequence
 from os import fsync
-from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Type
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Type, Union
 
 from requests import Response
 
@@ -14,6 +15,8 @@
 if TYPE_CHECKING:
     from .client import NuxeoClient
 
+logger = logging.getLogger(__name__)
+
 # Types allowed for operations parameters
 # See https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html
 # for default values
@@ -165,6 +168,11 @@ def execute(
 
         command, input_obj, params, context = self.get_attributes(operation, **kwargs)
 
+        # ── REQUEST TRANSLATION: username → generated UID ──
+        # Before param validation and sending, replace any username values
+        # in known param keys with their corresponding generated UIDs.
+        params = self.client._translate_request_params(params)
+
         if check_params:
             self.check_params(command, params)
 
@@ -208,7 +216,8 @@ def execute(
 
         if json:
             try:
-                return resp.json()
+                result = resp.json()
+                return result
             except ValueError:
                 pass
         return resp.content