feat: pin frequent mobile work (Closes #1477)

src/main.py

@@ -980,6 +980,10 @@ class RecentWorkItem(BaseModel):
     route: str = Field(min_length=1, max_length=300)
 
 
+class RecentWorkRoute(BaseModel):
+    route: str = Field(min_length=1, max_length=300)
+
+
 class CompletedFiledReviewReceipt(BaseModel):
     repository: str = Field(
         min_length=3,
@@ -3468,6 +3472,40 @@ async def record_recent_work(payload: RecentWorkItem):
         )
 
 
+@app.put("/api/v1/recent-work/pin")
+async def pin_recent_work(payload: RecentWorkItem):
+    login = await _confirmed_login()
+    try:
+        return await asyncio.to_thread(
+            _recent_work_store().pin, login, payload.model_dump()
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    except (OSError, sqlite3.Error, PrivateStateEncryptionError):
+        raise HTTPException(
+            status_code=503,
+            detail="Recent work synchronization is unavailable",
+            headers={"Retry-After": "1"},
+        )
+
+
+@app.delete("/api/v1/recent-work/pin")
+async def unpin_recent_work(payload: RecentWorkRoute):
+    login = await _confirmed_login()
+    try:
+        return await asyncio.to_thread(
+            _recent_work_store().unpin, login, payload.route
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    except (OSError, sqlite3.Error, PrivateStateEncryptionError):
+        raise HTTPException(
+            status_code=503,
+            detail="Recent work synchronization is unavailable",
+            headers={"Retry-After": "1"},
+        )
+
+
 @app.get("/api/v1/unfiled-drafts")
 async def get_unfiled_drafts(response: Response):
     login = await _confirmed_login()

src/recent_work_store.py

@@ -18,10 +18,12 @@ class RecentWorkStore:
         timeout: float = 1.0,
         encryption_key: bytes | None = None,
         limit: int = 5,
+        pinned_limit: int = 20,
     ):
         self.path = Path(path)
         self.timeout = timeout
         self.limit = max(1, int(limit))
+        self.pinned_limit = max(1, int(pinned_limit))
         self._cipher = PrivateStateCipher(
             encryption_key if encryption_key is not None else private_state_encryption_config(),
             store="recent-work",
@@ -86,30 +88,47 @@ class RecentWorkStore:
             raise ValueError("recent work item is invalid")
         return normalized
 
-    def _items(self, row, login: str) -> tuple[list[dict], bool]:
+    def _state(self, row, login: str) -> tuple[dict, bool]:
         if row is None:
-            return [], False
+            return {"items": [], "pinned": []}, False
         payload, legacy = self._cipher.open(row[0], binding=f"items:{login}")
-        if not isinstance(payload, list):
+        if isinstance(payload, list):
+            payload = {"items": payload, "pinned": []}
+            legacy = True
+        if not isinstance(payload, dict) or not isinstance(payload.get("items"), list) or not isinstance(payload.get("pinned"), list):
             raise PrivateStateEncryptionError("private state could not be decrypted")
         try:
-            return [self._normalize(item) for item in payload][: self.limit], legacy
+            items = [self._normalize(item) for item in payload["items"]][: self.limit]
+            pinned = [self._normalize(item) for item in payload["pinned"]][: self.pinned_limit]
+            if len({item["route"] for item in pinned}) != len(pinned):
+                raise ValueError("recent work item is invalid")
+            return {"items": items, "pinned": pinned}, legacy
         except ValueError as error:
             raise PrivateStateEncryptionError("private state could not be decrypted") from error
 
+    def _seal(self, state: dict, login: str) -> str:
+        return self._cipher.seal(state, binding=f"items:{login}")
+
+    def _write(self, connection: sqlite3.Connection, login: str, state: dict) -> None:
+        connection.execute(
+            "INSERT INTO recent_work(login, items) VALUES (?, ?) "
+            "ON CONFLICT(login) DO UPDATE SET items=excluded.items",
+            (login, self._seal(state, login)),
+        )
+
     def get(self, login: str) -> dict:
         login = self._login(login)
         with self._connect() as connection:
             row = connection.execute(
                 "SELECT items FROM recent_work WHERE login = ?", (login,)
             ).fetchone()
-            items, legacy = self._items(row, login)
+            state, legacy = self._state(row, login)
             if row is not None and legacy:
                 connection.execute(
                     "UPDATE recent_work SET items = ? WHERE login = ? AND items = ?",
-                    (self._cipher.seal(items, binding=f"items:{login}"), login, row[0]),
+                    (self._seal(state, login), login, row[0]),
                 )
-        return {"items": items}
+        return state
 
     def record(self, login: str, item: dict) -> dict:
         login = self._login(login)
@@ -119,13 +138,41 @@ class RecentWorkStore:
             row = connection.execute(
                 "SELECT items FROM recent_work WHERE login = ?", (login,)
             ).fetchone()
-            current, _legacy = self._items(row, login)
-            items = [normalized, *(entry for entry in current if entry["route"] != normalized["route"])]
-            items = items[: self.limit]
-            sealed = self._cipher.seal(items, binding=f"items:{login}")
-            connection.execute(
-                "INSERT INTO recent_work(login, items) VALUES (?, ?) "
-                "ON CONFLICT(login) DO UPDATE SET items=excluded.items",
-                (login, sealed),
-            )
-        return {"items": items}
+            state, _legacy = self._state(row, login)
+            state["items"] = [normalized, *(entry for entry in state["items"] if entry["route"] != normalized["route"])][: self.limit]
+            state["pinned"] = [
+                normalized if entry["route"] == normalized["route"] else entry
+                for entry in state["pinned"]
+            ]
+            self._write(connection, login, state)
+        return state
+
+    def pin(self, login: str, item: dict) -> dict:
+        login = self._login(login)
+        normalized = self._normalize(item)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT items FROM recent_work WHERE login = ?", (login,)
+            ).fetchone()
+            state, _legacy = self._state(row, login)
+            state["pinned"] = [
+                normalized,
+                *(entry for entry in state["pinned"] if entry["route"] != normalized["route"]),
+            ][: self.pinned_limit]
+            self._write(connection, login, state)
+        return state
+
+    def unpin(self, login: str, route: str) -> dict:
+        login = self._login(login)
+        if not isinstance(route, str) or not route:
+            raise ValueError("recent work route is invalid")
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT items FROM recent_work WHERE login = ?", (login,)
+            ).fetchone()
+            state, _legacy = self._state(row, login)
+            state["pinned"] = [entry for entry in state["pinned"] if entry["route"] != route]
+            self._write(connection, login, state)
+        return state