lfss 0.7.14__py3-none-any.whl → 0.8.0__py3-none-any.whl

lfss/src/database.py

@@ -10,10 +10,13 @@ import aiosqlite, aiofiles
 import aiofiles.os
 
 from .connection_pool import execute_sql, unique_cursor, transaction
-from .datatype import UserRecord, FileReadPermission, FileRecord, DirectoryRecord, PathContents
+from .datatype import (
+    UserRecord, FileReadPermission, FileRecord, DirectoryRecord, PathContents, 
+    FileSortKey, DirSortKey, isValidFileSortKey, isValidDirSortKey
+    )
 from .config import LARGE_BLOB_DIR, CHUNK_SIZE
 from .log import get_logger
-from .utils import decode_uri_compnents, hash_credential, concurrent_wrap
+from .utils import decode_uri_compnents, hash_credential, concurrent_wrap, debounce_async
 from .error import *
 
 class DBObjectBase(ABC):
@@ -156,55 +159,108 @@ class FileConn(DBObjectBase):
             dirs = [await self.get_path_record(u) for u in dirnames] if not skim else [DirectoryRecord(u) for u in dirnames]
             return dirs
     
-    async def list_path(self, url: str, flat: bool = False) -> PathContents:
-        """
-        List all files and directories under the given path
-        if flat is True, list all files under the path, with out delimiting directories
-        """
-        self.logger.debug(f"Listing path {url}, flat={flat}")
-        if not url.endswith('/'):
-            url += '/'
-        if url == '/':
-            # users cannot be queried using '/', because we store them without '/' prefix, 
-            # so we need to handle this case separately, 
-            if flat:
-                cursor = await self.cur.execute("SELECT * FROM fmeta")
-                res = await cursor.fetchall()
-                files = [self.parse_record(r) for r in res]
-                return PathContents([], files)
+    async def count_path_dirs(self, url: str):
+        if not url.endswith('/'): url += '/'
+        if url == '/': url = ''
+        cursor = await self.cur.execute("""
+        SELECT COUNT(*) FROM (
+            SELECT DISTINCT SUBSTR( 
+                url, LENGTH(?) + 1, 
+                INSTR(SUBSTR(url, LENGTH(?) + 1), '/')
+                ) AS dirname
+            FROM fmeta WHERE url LIKE ? AND dirname != ''
+        )
+        """, (url, url, url + '%'))
+        res = await cursor.fetchone()
+        assert res is not None, "Error: count_path_dirs"
+        return res[0]
 
+    async def list_path_dirs(
+        self, url: str, 
+        offset: int = 0, limit: int = int(1e5), 
+        order_by: DirSortKey = '', order_desc: bool = False,
+        skim: bool = True
+        ) -> list[DirectoryRecord]:
+        if not isValidDirSortKey(order_by):
+            raise ValueError(f"Invalid order_by ({order_by})")
+
+        if not url.endswith('/'): url += '/'
+        if url == '/': url = ''
+
+        sql_qury = """
+            SELECT DISTINCT SUBSTR(
+                url, 
+                1 + LENGTH(?),
+                INSTR(SUBSTR(url, 1 + LENGTH(?)), '/')
+            ) AS dirname 
+            FROM fmeta WHERE url LIKE ? AND dirname != ''
+        """ \
+        + (f"ORDER BY {order_by} {'DESC' if order_desc else 'ASC'}" if order_by else '') \
+        + " LIMIT ? OFFSET ?"
+        cursor = await self.cur.execute(sql_qury, (url, url, url + '%', limit, offset))
+        res = await cursor.fetchall()
+        dirs_str = [r[0] for r in res]
+        async def get_dir(dir_url):
+            if skim:
+                return DirectoryRecord(dir_url)
             else:
-                return PathContents(await self.list_root_dirs(), [])
-        
+                return await self.get_path_record(dir_url)
+        dirs = await asyncio.gather(*[get_dir(url + d) for d in dirs_str])
+        return dirs
+    
+    async def count_path_files(self, url: str, flat: bool = False):
+        if not url.endswith('/'): url += '/'
+        if url == '/': url = ''
         if flat:
-            cursor = await self.cur.execute("SELECT * FROM fmeta WHERE url LIKE ?", (url + '%', ))
-            res = await cursor.fetchall()
-            files = [self.parse_record(r) for r in res]
-            return PathContents([], files)
+            cursor = await self.cur.execute("SELECT COUNT(*) FROM fmeta WHERE url LIKE ?", (url + '%', ))
+        else:
+            cursor = await self.cur.execute("SELECT COUNT(*) FROM fmeta WHERE url LIKE ? AND url NOT LIKE ?", (url + '%', url + '%/%'))
+        res = await cursor.fetchone()
+        assert res is not None, "Error: count_path_files"
+        return res[0]
 
-        cursor = await self.cur.execute("SELECT * FROM fmeta WHERE url LIKE ? AND url NOT LIKE ?", (url + '%', url + '%/%'))
+    async def list_path_files(
+        self, url: str, 
+        offset: int = 0, limit: int = int(1e5), 
+        order_by: FileSortKey = '', order_desc: bool = False,
+        flat: bool = False, 
+        ) -> list[FileRecord]:
+        if not isValidFileSortKey(order_by):
+            raise ValueError(f"Invalid order_by {order_by}")
+
+        if not url.endswith('/'): url += '/'
+        if url == '/': url = ''
+
+        sql_query = "SELECT * FROM fmeta WHERE url LIKE ?"
+        if not flat: sql_query += " AND url NOT LIKE ?"
+        if order_by: sql_query += f" ORDER BY {order_by} {'DESC' if order_desc else 'ASC'}"
+        sql_query += " LIMIT ? OFFSET ?"
+        if flat:
+            cursor = await self.cur.execute(sql_query, (url + '%', limit, offset))
+        else:
+            cursor = await self.cur.execute(sql_query, (url + '%', url + '%/%', limit, offset))
         res = await cursor.fetchall()
         files = [self.parse_record(r) for r in res]
-
-        # substr indexing starts from 1
-        cursor = await self.cur.execute(
-            """
-            SELECT DISTINCT 
-                SUBSTR(
-                    url, 
-                    1 + LENGTH(?),
-                    INSTR(SUBSTR(url, 1 + LENGTH(?)), '/') - 1
-                ) AS subdir 
-                FROM fmeta WHERE url LIKE ?
-            """, 
-            (url, url, url + '%')
+        return files
+    
+    async def list_path(self, url: str) -> PathContents:
+        """
+        List all files and directories under the given path.  
+        This method is a handy way file browsing, but has limitaions:
+        - It does not support pagination
+        - It does not support sorting
+        - It cannot flatten directories
+        - It cannot list directories with details
+        """
+        MAX_ITEMS = int(1e4)
+        dir_count = await self.count_path_dirs(url)
+        file_count = await self.count_path_files(url, flat=False)
+        if dir_count + file_count > MAX_ITEMS:
+            raise TooManyItemsError("Too many items, please paginate")
+        return PathContents(
+            dirs = await self.list_path_dirs(url, skim=True, limit=MAX_ITEMS),
+            files = await self.list_path_files(url, flat=False, limit=MAX_ITEMS)
             )
-        res = await cursor.fetchall()
-        dirs_str = [r[0] + '/' for r in res if r[0] != '/']
-        async def get_dir(dir_url):
-            return DirectoryRecord(dir_url, -1)
-        dirs = await asyncio.gather(*[get_dir(url + d) for d in dirs_str])
-        return PathContents(dirs, files)
     
     async def get_path_record(self, url: str) -> DirectoryRecord:
         """
@@ -361,7 +417,8 @@ class FileConn(DBObjectBase):
     async def set_file_blob(self, file_id: str, blob: bytes):
         await self.cur.execute("INSERT OR REPLACE INTO blobs.fdata (file_id, data) VALUES (?, ?)", (file_id, blob))
     
-    async def set_file_blob_external(self, file_id: str, stream: AsyncIterable[bytes])->int:
+    @staticmethod
+    async def set_file_blob_external(file_id: str, stream: AsyncIterable[bytes])->int:
         size_sum = 0
         try:
             async with aiofiles.open(LARGE_BLOB_DIR / file_id, 'wb') as f:
@@ -389,7 +446,8 @@ class FileConn(DBObjectBase):
                 if not chunk: break
                 yield chunk
     
-    async def delete_file_blob_external(self, file_id: str):
+    @staticmethod
+    async def delete_file_blob_external(file_id: str):
         if (LARGE_BLOB_DIR / file_id).exists():
             await aiofiles.os.remove(LARGE_BLOB_DIR / file_id)
     
@@ -399,6 +457,36 @@ class FileConn(DBObjectBase):
     async def delete_file_blobs(self, file_ids: list[str]):
         await self.cur.execute("DELETE FROM blobs.fdata WHERE file_id IN ({})".format(','.join(['?'] * len(file_ids))), file_ids)
 
+_log_active_queue = []
+_log_active_lock = asyncio.Lock()
+@debounce_async()
+async def _set_all_active():
+    async with transaction() as conn:
+        uconn = UserConn(conn)
+        async with _log_active_lock:
+            for u in _log_active_queue:
+                await uconn.set_active(u)
+            _log_active_queue.clear()
+async def delayed_log_activity(username: str):
+    async with _log_active_lock:
+        _log_active_queue.append(username)
+    await _set_all_active()
+
+_log_access_queue = []
+_log_access_lock = asyncio.Lock()
+@debounce_async()
+async def _log_all_access():
+    async with transaction() as conn:
+        fconn = FileConn(conn)
+        async with _log_access_lock:
+            for r in _log_access_queue:
+                await fconn.log_access(r)
+            _log_access_queue.clear()
+async def delayed_log_access(url: str):
+    async with _log_access_lock:
+        _log_access_queue.append(url)
+    await _log_all_access()
+
 def validate_url(url: str, is_file = True):
     prohibited_chars = ['..', ';', "'", '"', '\\', '\0', '\n', '\r', '\t', '\x0b', '\x0c']
     ret = not url.startswith('/') and not url.startswith('_') and not url.startswith('.')
@@ -433,11 +521,6 @@ class Database:
             await execute_sql(conn, 'init.sql')
         return self
     
-    async def record_user_activity(self, u: str):
-        async with transaction() as conn:
-            uconn = UserConn(conn)
-            await uconn.set_active(u)
-    
     async def update_file_record(self, user: UserRecord, url: str, permission: FileReadPermission):
         validate_url(url)
         async with transaction() as conn:
@@ -459,9 +542,7 @@ class Database:
         if file_size is not provided, the blob must be bytes
         """
         validate_url(url)
-        async with transaction() as cur:
-            uconn = UserConn(cur)
-            fconn = FileConn(cur)
+        async with unique_cursor() as cur:
             user = await get_user(cur, u)
             if user is None:
                 return
@@ -477,27 +558,35 @@ class Database:
                     if await get_user(cur, first_component) is None:
                         raise PermissionDeniedError(f"Invalid path: {first_component} is not a valid username")
             
-            user_size_used = await fconn.user_size(user.id)
+            fconn_r = FileConn(cur)
+            user_size_used = await fconn_r.user_size(user.id)
+
             if isinstance(blob, bytes):
                 file_size = len(blob)
                 if user_size_used + file_size > user.max_storage:
                     raise StorageExceededError(f"Unable to save file, user {user.username} has storage limit of {user.max_storage}, used {user_size_used}, requested {file_size}")
                 f_id = uuid.uuid4().hex
-                await fconn.set_file_blob(f_id, blob)
-                await fconn.set_file_record(
-                    url, owner_id=user.id, file_id=f_id, file_size=file_size, 
-                    permission=permission, external=False, mime_type=mime_type)
+
+                async with transaction() as w_cur:
+                    fconn_w = FileConn(w_cur)
+                    await fconn_w.set_file_blob(f_id, blob)
+                    await fconn_w.set_file_record(
+                        url, owner_id=user.id, file_id=f_id, file_size=file_size, 
+                        permission=permission, external=False, mime_type=mime_type)
             else:
                 assert isinstance(blob, AsyncIterable)
                 f_id = uuid.uuid4().hex
-                file_size = await fconn.set_file_blob_external(f_id, blob)
+                file_size = await FileConn.set_file_blob_external(f_id, blob)
                 if user_size_used + file_size > user.max_storage:
-                    await fconn.delete_file_blob_external(f_id)
+                    await FileConn.delete_file_blob_external(f_id)
                     raise StorageExceededError(f"Unable to save file, user {user.username} has storage limit of {user.max_storage}, used {user_size_used}, requested {file_size}")
-                await fconn.set_file_record(
-                    url, owner_id=user.id, file_id=f_id, file_size=file_size, 
-                    permission=permission, external=True, mime_type=mime_type)
-            await uconn.set_active(user.username)
+                
+                async with transaction() as w_cur:
+                    await FileConn(w_cur).set_file_record(
+                        url, owner_id=user.id, file_id=f_id, file_size=file_size, 
+                        permission=permission, external=True, mime_type=mime_type)
+            
+        await delayed_log_activity(user.username)
 
     async def read_file_stream(self, url: str) -> AsyncIterable[bytes]:
         validate_url(url)
@@ -510,9 +599,7 @@ class Database:
                 raise ValueError(f"File {url} is not stored externally, should use read_file instead")
             ret = fconn.get_file_blob_external(r.file_id)
 
-        async with transaction() as w_cur:
-            await FileConn(w_cur).log_access(url)
-        
+        await delayed_log_access(url)
         return ret
 
 
@@ -532,9 +619,7 @@ class Database:
             if blob is None:
                 raise FileNotFoundError(f"File {url} data not found")
 
-        async with transaction() as w_cur:
-            await FileConn(w_cur).log_access(url)
-
+        await delayed_log_access(url)
         return blob
 
     async def delete_file(self, url: str, assure_user: Optional[UserRecord] = None) -> Optional[FileRecord]:
@@ -653,7 +738,8 @@ class Database:
         async with unique_cursor() as cur:
             fconn = FileConn(cur)
             if urls is None:
-                urls = [r.url for r in (await fconn.list_path(top_url, flat=True)).files]
+                fcount = await fconn.count_path_files(top_url, flat=True)
+                urls = [r.url for r in (await fconn.list_path_files(top_url, flat=True, limit=fcount))]
 
             for url in urls:
                 if not url.startswith(top_url):

lfss/src/datatype.py

@@ -1,4 +1,5 @@
 from enum import IntEnum
+from typing import Literal
 import dataclasses
 
 class FileReadPermission(IntEnum):
@@ -51,6 +52,10 @@ class DirectoryRecord:
 
 @dataclasses.dataclass
 class PathContents:
-    dirs: list[DirectoryRecord]
-    files: list[FileRecord]
-    
+    dirs: list[DirectoryRecord] = dataclasses.field(default_factory=list)
+    files: list[FileRecord] = dataclasses.field(default_factory=list)
+    
+FileSortKey = Literal['', 'url', 'file_size', 'create_time', 'access_time', 'mime_type']
+isValidFileSortKey = lambda x: x in ['', 'url', 'file_size', 'create_time', 'access_time', 'mime_type']
+DirSortKey = Literal['', 'dirname']
+isValidDirSortKey = lambda x: x in ['', 'dirname']

lfss/src/error.py

@@ -7,4 +7,6 @@ class PermissionDeniedError(LFSSExceptionBase, PermissionError):...
 
 class InvalidPathError(LFSSExceptionBase, ValueError):...
 
-class StorageExceededError(LFSSExceptionBase):...
+class StorageExceededError(LFSSExceptionBase):...
+
+class TooManyItemsError(LFSSExceptionBase):...

lfss/src/server.py

@@ -16,9 +16,13 @@ from .error import *
 from .log import get_logger
 from .stat import RequestDB
 from .config import MAX_BUNDLE_BYTES, MAX_FILE_BYTES, LARGE_FILE_BYTES, CHUNK_SIZE
-from .utils import ensure_uri_compnents, format_last_modified, now_stamp
+from .utils import ensure_uri_compnents, format_last_modified, now_stamp, wait_for_debounce_tasks
 from .connection_pool import global_connection_init, global_connection_close, unique_cursor
-from .database import Database, UserRecord, DECOY_USER, FileRecord, check_user_permission, FileReadPermission, UserConn, FileConn, PathContents
+from .database import Database, DECOY_USER, check_user_permission, UserConn, FileConn, delayed_log_activity
+from .datatype import (
+    FileReadPermission, FileRecord, UserRecord, PathContents, 
+    FileSortKey, DirSortKey
+)
 from .thumb import get_thumb
 
 logger = get_logger("server", term_level="DEBUG")
@@ -35,6 +39,7 @@ async def lifespan(app: FastAPI):
         yield
         await req_conn.commit()
     finally:
+        await wait_for_debounce_tasks()
         await asyncio.gather(req_conn.close(), global_connection_close())
 
 def handle_exception(fn):
@@ -49,6 +54,7 @@ def handle_exception(fn):
             if isinstance(e, InvalidPathError): raise HTTPException(status_code=400, detail=str(e))
             if isinstance(e, FileNotFoundError): raise HTTPException(status_code=404, detail=str(e))
             if isinstance(e, FileExistsError): raise HTTPException(status_code=409, detail=str(e))
+            if isinstance(e, TooManyItemsError): raise HTTPException(status_code=400, detail=str(e))
             logger.error(f"Uncaptured error in {fn.__name__}: {e}")
             raise 
     return wrapper
@@ -182,7 +188,7 @@ async def emit_file(
 @handle_exception
 async def get_file(
     path: str, 
-    download: bool = False, flat: bool = False, thumb: bool = False,
+    download: bool = False, thumb: bool = False,
     user: UserRecord = Depends(get_current_user)
     ):
     path = ensure_uri_compnents(path)
@@ -199,8 +205,6 @@ async def get_file(
                 return await emit_thumbnail(path, download, create_time=None)
             
             if path == "/":
-                if flat:
-                    raise HTTPException(status_code=400, detail="Flat query not supported for root path")
                 return PathContents(
                     dirs = await fconn.list_root_dirs(user.username, skim=True) \
                         if not user.is_admin else await fconn.list_root_dirs(skim=True),
@@ -210,7 +214,7 @@ async def get_file(
             if not path.startswith(f"{user.username}/") and not user.is_admin:
                 raise HTTPException(status_code=403, detail="Permission denied, path must start with username")
 
-            return await fconn.list_path(path, flat = flat)
+            return await fconn.list_path(path)
     
     # handle file query
     async with unique_cursor() as conn:
@@ -332,7 +336,7 @@ async def delete_file(path: str, user: UserRecord = Depends(registered_user)):
     else:
         res = await db.delete_file(path, user if not user.is_admin else None)
 
-    await db.record_user_activity(user.username)
+    await delayed_log_activity(user.username)
     if res:
         return Response(status_code=200, content="Deleted")
     else:
@@ -366,7 +370,10 @@ async def bundle_files(path: str, user: UserRecord = Depends(registered_user)):
     
     async with unique_cursor() as conn:
         fconn = FileConn(conn)
-        files = (await fconn.list_path(path, flat = True)).files
+        files = await fconn.list_path_files(
+            url = path, flat = True, 
+            limit=(await fconn.count_path_files(url = path, flat = True))
+            )
     files = [f for f in files if await is_access_granted(f)]
     if len(files) == 0:
         raise HTTPException(status_code=404, detail="No files found")
@@ -421,7 +428,7 @@ async def update_file_meta(
     path = ensure_uri_compnents(path)
     if path.startswith("/"):
         path = path[1:]
-    await db.record_user_activity(user.username)
+    await delayed_log_activity(user.username)
 
     # file
     if not path.endswith("/"):
@@ -448,6 +455,57 @@ async def update_file_meta(
             await db.move_path(user, path, new_path)
 
     return Response(status_code=200, content="OK")
+
+async def validate_path_permission(path: str, user: UserRecord):
+    if not path.endswith("/"):
+        raise HTTPException(status_code=400, detail="Path must end with /")
+    if not path.startswith(f"{user.username}/") and not user.is_admin:
+        raise HTTPException(status_code=403, detail="Permission denied")
+
+@router_api.get("/count-files")
+async def count_files(path: str, flat: bool = False, user: UserRecord = Depends(registered_user)):
+    await validate_path_permission(path, user)
+    path = ensure_uri_compnents(path)
+    async with unique_cursor() as conn:
+        fconn = FileConn(conn)
+        return { "count": await fconn.count_path_files(url = path, flat = flat) }
+@router_api.get("/list-files")
+async def list_files(
+    path: str, offset: int = 0, limit: int = 1000,
+    order_by: FileSortKey = "", order_desc: bool = False,
+    flat: bool = False, user: UserRecord = Depends(registered_user)
+    ):
+    await validate_path_permission(path, user)
+    path = ensure_uri_compnents(path)
+    async with unique_cursor() as conn:
+        fconn = FileConn(conn)
+        return await fconn.list_path_files(
+            url = path, offset = offset, limit = limit,
+            order_by=order_by, order_desc=order_desc, 
+            flat=flat
+        )
+
+@router_api.get("/count-dirs")
+async def count_dirs(path: str, user: UserRecord = Depends(registered_user)):
+    await validate_path_permission(path, user)
+    path = ensure_uri_compnents(path)
+    async with unique_cursor() as conn:
+        fconn = FileConn(conn)
+        return { "count": await fconn.count_path_dirs(url = path) }
+@router_api.get("/list-dirs")
+async def list_dirs(
+    path: str, offset: int = 0, limit: int = 1000,
+    order_by: DirSortKey = "", order_desc: bool = False,
+    skim: bool = True, user: UserRecord = Depends(registered_user)
+    ):
+    await validate_path_permission(path, user)
+    path = ensure_uri_compnents(path)
+    async with unique_cursor() as conn:
+        fconn = FileConn(conn)
+        return await fconn.list_path_dirs(
+            url = path, offset = offset, limit = limit,
+            order_by=order_by, order_desc=order_desc, skim=skim
+        )
     
 @router_api.get("/whoami")
 @handle_exception

lfss/src/stat.py

@@ -42,7 +42,7 @@ class RequestDB:
     async def commit(self):
         await self.conn.commit()
     
-    @debounce_async(0.05)
+    @debounce_async()
     async def ensure_commit_once(self):
         await self.commit()
     

lfss/src/thumb.py

@@ -5,6 +5,7 @@ from typing import Optional
 from PIL import Image
 from io import BytesIO
 import aiosqlite
+from contextlib import asynccontextmanager
 
 async def _maybe_init_thumb(c: aiosqlite.Cursor):
     await c.execute('''
@@ -49,6 +50,13 @@ async def _delete_cache_thumb(c: aiosqlite.Cursor, path: str):
     ''', (path, ))
     await c.execute('COMMIT')
 
+@asynccontextmanager
+async def cache_cursor():
+    async with aiosqlite.connect(THUMB_DB) as conn:
+        cur = await conn.cursor()
+        await _maybe_init_thumb(cur)
+        yield cur
+
 async def get_thumb(path: str) -> Optional[tuple[bytes, str]]:
     """
     returns [image bytes of thumbnail, mime type] if supported, 
@@ -58,20 +66,17 @@ async def get_thumb(path: str) -> Optional[tuple[bytes, str]]:
     if path.endswith('/'):
         return None
 
-    async with aiosqlite.connect(THUMB_DB) as conn:
-        cur = await conn.cursor()
-        await _maybe_init_thumb(cur)
-
-        async with unique_cursor() as main_c:
-            fconn = FileConn(main_c)
-            r = await fconn.get_file_record(path)
-            if r is None:
+    async with unique_cursor() as main_c:
+        fconn = FileConn(main_c)
+        r = await fconn.get_file_record(path)
+        if r is None:
+            async with cache_cursor() as cur:
                 await _delete_cache_thumb(cur, path)
-                raise FileNotFoundError(f'File not found: {path}')
-        
-            if not r.mime_type.startswith('image/'):
-                return None
+            raise FileNotFoundError(f'File not found: {path}')
+        if not r.mime_type.startswith('image/'):
+            return None
 
+    async with cache_cursor() as cur:
         c_time = r.create_time
         thumb_blob = await _get_cache_thumb(cur, path, c_time)
         if thumb_blob is not None:

lfss/src/utils.py

@@ -1,11 +1,14 @@
-import datetime
+import datetime, time
 import urllib.parse
 import asyncio
 import functools
 import hashlib
+from asyncio import Lock
+from collections import OrderedDict
 from concurrent.futures import ThreadPoolExecutor
 from typing import TypeVar, Callable, Awaitable
 from functools import wraps, partial
+from uuid import uuid4
 import os
 
 def hash_credential(username: str, password: str):
@@ -25,25 +28,56 @@ def ensure_uri_compnents(path: str):
     """ Ensure the path components are safe to use """
     return encode_uri_compnents(decode_uri_compnents(path))
 
-def debounce_async(delay: float = 0):
-    """ Debounce the async procedure """
+g_debounce_tasks: OrderedDict[str, asyncio.Task] = OrderedDict()
+lock_debounce_task_queue = Lock()
+async def wait_for_debounce_tasks():
+    async def stop_task(task: asyncio.Task):
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+    await asyncio.gather(*map(stop_task, g_debounce_tasks.values()))
+    g_debounce_tasks.clear()
+
+def debounce_async(delay: float = 0.1, max_wait: float = 1.):
+    """ 
+    Debounce the async procedure, 
+    ensuring execution at least once every `max_wait` seconds. 
+    """
     def debounce_wrap(func):
-        # https://docs.python.org/3/library/asyncio-task.html#asyncio.Task.cancel
+        task_record: tuple[str, asyncio.Task] | None = None
+        last_execution_time = 0
+
         async def delayed_func(*args, **kwargs):
+            nonlocal last_execution_time
             await asyncio.sleep(delay)
             await func(*args, **kwargs)
+            last_execution_time = time.monotonic()
 
-        task_record: asyncio.Task | None = None
         @functools.wraps(func)
         async def wrapper(*args, **kwargs):
-            nonlocal task_record
-            if task_record is not None:
-                task_record.cancel()
-            task_record = asyncio.create_task(delayed_func(*args, **kwargs))
-            try:
-                await task_record
-            except asyncio.CancelledError:
-                pass
+            nonlocal task_record, last_execution_time
+
+            async with lock_debounce_task_queue:
+                if task_record is not None:
+                    task_record[1].cancel()
+                    g_debounce_tasks.pop(task_record[0], None)
+            
+            if time.monotonic() - last_execution_time > max_wait:
+                await func(*args, **kwargs)
+                last_execution_time = time.monotonic()
+                return
+
+            task = asyncio.create_task(delayed_func(*args, **kwargs))
+            task_uid = uuid4().hex
+            task_record = (task_uid, task)
+            async with lock_debounce_task_queue:
+                g_debounce_tasks[task_uid] = task
+                if len(g_debounce_tasks) > 2048:
+                    # finished tasks are not removed from the dict
+                    # so we need to clear it periodically
+                    await wait_for_debounce_tasks()
         return wrapper
     return debounce_wrap