docs(code): add concise docstrings

src/gapido_auth/infrastructure/mongo_repositories.py

@@ -10,10 +10,12 @@ from gapido_auth.domain.ports import RefreshSessionRepository, UserRepository
 
 
 def _now() -> datetime:
+    """Return timezone-aware UTC now for Mongo document timestamps."""
     return datetime.now(UTC)
 
 
 def _user_from_doc(doc: dict[str, Any]) -> User:
+    """Map a Mongo user document into the domain entity."""
     return User(
         id=str(doc["_id"]),
         mobile=str(doc["mobile"]),
@@ -25,6 +27,7 @@ def _user_from_doc(doc: dict[str, Any]) -> User:
 
 
 def _session_from_doc(doc: dict[str, Any]) -> RefreshSession:
+    """Map a Mongo refresh-session document into the domain entity."""
     return RefreshSession(
         id=str(doc["_id"]),
         user_id=str(doc["user_id"]),
@@ -37,24 +40,35 @@ def _session_from_doc(doc: dict[str, Any]) -> RefreshSession:
 
 
 class MongoUserRepository(UserRepository):
+    """MongoDB adapter for user documents and admin bootstrap."""
+
     def __init__(self, db: AsyncIOMotorDatabase[Any]) -> None:
+        """Bind the repository to the users collection."""
         self._collection = db.users
 
     async def create_indexes(self) -> None:
+        """Create indexes required for unique mobile lookup and role scans."""
+
         await self._collection.create_index([("mobile", ASCENDING)], unique=True)
         await self._collection.create_index([("role", ASCENDING)])
 
     async def get_by_id(self, user_id: str) -> User | None:
+        """Return a user by Mongo ObjectId string, or None for invalid/missing ids."""
+
         if not ObjectId.is_valid(user_id):
             return None
         doc = await self._collection.find_one({"_id": ObjectId(user_id)})
         return _user_from_doc(doc) if doc else None
 
     async def get_by_mobile(self, mobile: str) -> User | None:
+        """Return the user registered for a mobile number if one exists."""
+
         doc = await self._collection.find_one({"mobile": mobile})
         return _user_from_doc(doc) if doc else None
 
     async def get_or_create_user(self, mobile: str, role: Role = Role.USER) -> User:
+        """Create a default active user for a verified mobile, or return the existing one."""
+
         now = _now()
         await self._collection.update_one(
             {"mobile": mobile},
@@ -75,6 +89,8 @@ class MongoUserRepository(UserRepository):
         return user
 
     async def ensure_admin_user(self, mobile: str) -> User:
+        """Idempotently seed or promote the configured admin mobile."""
+
         now = _now()
         await self._collection.update_one(
             {"mobile": mobile},
@@ -91,15 +107,22 @@ class MongoUserRepository(UserRepository):
 
 
 class MongoRefreshSessionRepository(RefreshSessionRepository):
+    """MongoDB adapter for hashed refresh-token sessions."""
+
     def __init__(self, db: AsyncIOMotorDatabase[Any]) -> None:
+        """Bind the repository to the refresh_sessions collection."""
         self._collection = db.refresh_sessions
 
     async def create_indexes(self) -> None:
+        """Create indexes used for token lookup, user session scans, and revocation."""
+
         await self._collection.create_index([("token_hash", ASCENDING)], unique=True)
         await self._collection.create_index([("user_id", ASCENDING), ("expires_at", ASCENDING)])
         await self._collection.create_index([("revoked_at", ASCENDING)])
 
     async def create(self, user_id: str, token_hash: str, expires_at: datetime) -> RefreshSession:
+        """Persist a new active refresh session for a user."""
+
         now = _now()
         result = await self._collection.insert_one(
             {
@@ -117,6 +140,8 @@ class MongoRefreshSessionRepository(RefreshSessionRepository):
         return _session_from_doc(doc)
 
     async def get_active_by_hash(self, token_hash: str, now: datetime) -> RefreshSession | None:
+        """Return a non-revoked, non-expired session by token hash."""
+
         doc = await self._collection.find_one(
             {"token_hash": token_hash, "revoked_at": None, "expires_at": {"$gt": now}}
         )
@@ -125,6 +150,8 @@ class MongoRefreshSessionRepository(RefreshSessionRepository):
     async def revoke(
         self, token_hash: str, now: datetime, replaced_by_hash: str | None = None
     ) -> None:
+        """Mark a refresh session revoked, optionally linking its replacement hash."""
+
         update: dict[str, Any] = {"revoked_at": now}
         if replaced_by_hash is not None:
             update["replaced_by_hash"] = replaced_by_hash
@@ -132,4 +159,3 @@ class MongoRefreshSessionRepository(RefreshSessionRepository):
             {"token_hash": token_hash, "revoked_at": None},
             {"$set": update},
         )
-