refactor: redesign/reimplement optional anonymous user

Author: rexzhang

README.md

@@ -57,19 +57,6 @@ docker run -dit --restart unless-stopped \
 
 [Documentation at GitHub Page](https://rexzhang.github.io/asgi-webdav/)
 
-## TODO
-
-- Digest auth support neon
-- SQL database provider
-- Test big(1GB+) file in MemoryProvider
-- display server info in page `/_/admin` or `/_/`
-- Fail2ban(docker)
-- NFSProvider
-- logout at the web page
-- Fix MemoryProvider with macOS finder(create new file)
-- rewrite MemoryProvider with mmap
-- generate template URL for share(read only)
-
 ## Related Projects
 
 - <https://github.com/bootrino/reactoxide>

TODO

@@ -0,0 +1,57 @@
+进行中:
+    ☐ 匿名账号支持
+        ✔ 重新设计 Config 部分 @done(25-10-08)
+        ✔ 匿名账号在账号清单中生效 @done(25-10-19)
+        ✔ 匿名账号能通过 HTTP Auth 登录 @done(25-10-19)
+        ✔ 账号验证错误后正确返回401 @done(25-10-29)
+        ✔ 匿名账号在没有权限的路径返回 401 @done(25-10-29)
+        ✔ 匿名用户下对没有权限的路径返回 401, 并强制触发浏览器提示输入账号密码 @done(25-10-30)
+    ☐ 配置文件现代化
+        保存对 JSON 格式的支持
+        TOML 作为配置文件的第一格式
+        ✔ pydantic => dataclass @done
+        ✔ 添加 TOML 支持 @done
+        ☐ 使用 TOML 方便方便添加注释的特性增加各种使用场景配置范例 @long-term
+        ☐ 以 TOML 下的可读性为标准,适当调整配置文件结构 @long-term
+
+长期性任务:
+    整理好后迁移到 github issues
+    - 更好的类型标注
+        主要解决类型推断问题, 提高对静态类型检查工具的支持
+        终极目标为: 能通过mypy的检查
+        - 在维护代码时顺便解决相关代码出现的类型推断错误
+        ☐ 消除 DAVRequest 相关的类型推断错误
+        ☐ 消除 DAVResponse 相关的类型推断错误
+    - 解耦/分离可作为第三方库的核心代码和实现应用的代码
+        降低耦合度, 让其他项目能更便捷的添加 webdav 能力
+        终极目标为: 实现将核心代码剥离为一个独立的库
+        - 核心代码作为 ASGI app 分发
+    - 文档问题
+        ☐ 规范文档结构
+        ☐ 文档自动部署失效问题
+
+待实现:
+    ☐ 重构 DAVResponse 来统一 401 的响应行为 @high @next-release
+        ☐ 浏览器请求才弹认证请求框, 服务器返回 401 时不弹认证框
+        ☐ 重构部分 DAVResponse 代码, 这个与压缩依赖部分一起修改
+        ☐ 顺带解决 litmus 的一个告警?
+    ☐ 移除第三方压缩依赖,添加sztd支持 @delay dataclass-wizard 不兼容 py3.14
+    ☐ Digest auth support neon @low @@deplay 需要时间过多
+
+待确定实现方案:
+    ☐ 统一 user/account 的概念 @low
+        当前 user/account 的概念是混合的, 在代码中也是
+        需要做出明确的定义和规则; 统一为一个名称?
+    ☐ 完善的 LDAP 支持 @high
+    ☐ display server info in page `/_/admin` or `/_/` @high
+    ☐ Fail2ban(docker) @critical
+    ☐ Fix MemoryProvider with macOS finder(create new file)
+    ☐ NFSProvider
+    ☐ Test big(1GB+) file in MemoryProvider
+    ☐ SQL database provider
+    ☐ 支持 docker health check
+
+待确定可行性:
+    ☐ generate random URL for share(read only) @high
+    ☐ rewrite MemoryProvider with mmap or other
+    ☐ logout at the web page

asgi_webdav/auth.py

@@ -23,7 +23,7 @@
 )
 from asgi_webdav.config import Config
 from asgi_webdav.constants import DAVUser
-from asgi_webdav.exception import DAVExceptionAuthFailed, DAVExceptionConfigPaserFailed
+from asgi_webdav.exception import DAVExceptionAuthFailed, DAVExceptionConfig
 from asgi_webdav.request import DAVRequest
 from asgi_webdav.response import DAVResponse
 
@@ -534,7 +534,7 @@ def build_request_digest(
 class DAVAuth:
     realm = "ASGI-WebDAV"
     user_mapping: dict[str, DAVUser]
-    anonymous_user: DAVUser | None = None
+    anonymous_auto_match_user: DAVUser | None = None
 
     def __init__(self, config: Config):
         self.config = config
@@ -551,15 +551,22 @@ def __init__(self, config: Config):
             self.user_mapping[config_account.username] = user
             logger.info(f"Register User: {user}")
 
-        if self.config.anonymous_username:
-            self.anonymous_user = self.user_mapping.get(self.config.anonymous_username)
-            if self.anonymous_user is None:
-                # TODO: check it in config's reinit funtion, raise first at config.py
-                raise DAVExceptionConfigPaserFailed(
-                    "please check config's anonymous_username"
-                )
-
-            logger.info(f"Register Anonymous User: {self.anonymous_user}")
+        if (
+            self.config.anonymous.enable
+            and self.config.anonymous.allow_missing_auth_header
+        ):
+            self.anonymous_auto_match_user = self.user_mapping.get(
+                self.config.anonymous.user.username
+            )
+            if self.anonymous_auto_match_user is None:
+                message = f"Anonymous auto match user: {self.config.anonymous.user.username} not found, please check config"
+                logger.error(message)
+                raise DAVExceptionConfig(message)
+
+            self.anonymous_auto_match_user.anonymous = True
+            logger.info(
+                f"Enable anonymous auto match, user: {self.config.anonymous.user.username}"
+            )
 
         self.http_basic_auth = HTTPBasicAuth(
             realm=self.realm,
@@ -569,15 +576,12 @@ def __init__(self, config: Config):
         self.http_digest_auth = HTTPDigestAuth(realm=self.realm, secret=uuid4().hex)
 
     async def pick_out_user(self, request: DAVRequest) -> tuple[DAVUser | None, str]:
-        # TODO: support special user name: anonymous
-
         authorization_header = request.headers.get(b"authorization")
         if authorization_header is None:
-            if self.anonymous_user is None:
+            if self.anonymous_auto_match_user is None:
                 return None, "miss header: authorization"
             else:
-                # Server has the anonymous option able
-                return self.anonymous_user, ""
+                return self.anonymous_auto_match_user, ""
 
         index = authorization_header.find(b" ")
         if index == -1:

asgi_webdav/config.py

@@ -16,7 +16,12 @@
 from asgi_webdav.constants import (
     DEFAULT_FILENAME_CONTENT_TYPE_MAPPING,
     DEFAULT_HTTP_BASIC_AUTH_CACHE_TIMEOUT,
+    DEFAULT_PASSWORD,
+    DEFAULT_PASSWORD_ANONYMOUS,
+    DEFAULT_PERMISSIONS,
     DEFAULT_SUFFIX_CONTENT_TYPE_MAPPING,
+    DEFAULT_USERNAME,
+    DEFAULT_USERNAME_ANONYMOUS,
     AppEntryParameters,
     DAVCompressLevel,
 )
@@ -44,6 +49,17 @@ class User:
     admin: bool = False
 
 
+@dataclass
+class Anonymous:
+    enable: bool = False
+    user: User = field(
+        default_factory=lambda: User(
+            DEFAULT_USERNAME_ANONYMOUS, DEFAULT_PASSWORD_ANONYMOUS, DEFAULT_PERMISSIONS
+        )
+    )
+    allow_missing_auth_header: bool = True
+
+
 @dataclass
 class HTTPBasicAuth:
     # enable: bool = True
@@ -149,7 +165,8 @@ class Logging:
 class Config(JSONPyWizard):
     # auth
     account_mapping: list[User] = field(default_factory=list)
-    anonymous_username: str = ""
+
+    anonymous: Anonymous = field(default_factory=Anonymous)
 
     http_basic_auth: HTTPBasicAuth = field(default_factory=HTTPBasicAuth)
     http_digest_auth: HTTPDigestAuth = field(default_factory=HTTPDigestAuth)
@@ -183,7 +200,7 @@ def _update_from_env_config(self):
                 User(
                     username=env_config.username,
                     password=env_config.password,
-                    permissions=["+"],
+                    permissions=DEFAULT_PERMISSIONS,
                 ),
             )
             logger.info(f"Add user from ENV: {self.account_mapping[0].username}")
@@ -208,7 +225,7 @@ def _update_from_app_args(self, aep: AppEntryParameters):
                 User(
                     username=aep.admin_user[0],
                     password=aep.admin_user[1],
-                    permissions=["+"],
+                    permissions=DEFAULT_PERMISSIONS,
                     admin=True,
                 ),
             )
@@ -228,17 +245,27 @@ def _update_from_app_args(self, aep: AppEntryParameters):
             else:
                 self.provider_mapping[root_path_index].uri = root_path_uri
 
-    def _fix_config(self):
-        # account_mapping
+    def _complete_config(self):
+        # auth - anonymous
+        if self.anonymous.enable:
+            self.account_mapping.append(self.anonymous.user)
+            logger.info(
+                f"Enable anonymous user: {self.anonymous.user.username}, permissions: {self.anonymous.user.permissions}, admin: {self.anonymous.user.admin}"
+            )
+
+        # auth - default(admin) user
         if len(self.account_mapping) == 0:
             self.account_mapping.append(
-                User(username="username", password="password", permissions=["+"])
+                User(
+                    username=DEFAULT_USERNAME,
+                    password=DEFAULT_PASSWORD,
+                    permissions=DEFAULT_PERMISSIONS,
+                    admin=True,
+                )
+            )
+            logger.warning(
+                f"Add defalut(admin) user: {DEFAULT_USERNAME}, password:{DEFAULT_PASSWORD}, permissions: {DEFAULT_PERMISSIONS}"
             )
-            logger.warning("Add defalut user: username/password")
-
-        if len(self.account_mapping) == 1:
-            self.account_mapping[0].admin = True
-            logger.warning("Set the only account as admin")
 
         # provider - default
         if len(self.provider_mapping) == 0:
@@ -263,7 +290,7 @@ def update_from_app_args_and_env_and_default_value(self, aep: AppEntryParameters
         """
         self._update_from_env_config()
         self._update_from_app_args(aep)
-        self._fix_config()
+        self._complete_config()
 
 
 _config: Config = Config()
@@ -273,20 +300,24 @@ def get_config() -> Config:
     return _config
 
 
-def get_config_copy_from_dict(data: dict) -> Config:
-    return Config.from_dict(data)
+def get_config_copy_from_dict(data: dict, complete_config: bool = False) -> Config:
+    config = Config.from_dict(data)
+    if complete_config:
+        config._complete_config()
+
+    return config
 
 
-def reinit_config_from_dict(data: dict) -> Config:
+def reinit_config_from_dict(data: dict, complete_config: bool = False) -> Config:
     global _config
 
     logger.debug("Load config value from python object(dict)")
-    _config = get_config_copy_from_dict(data)
+    _config = get_config_copy_from_dict(data, complete_config)
 
     return _config
 
 
-def reinit_config_from_file(file_name: str) -> bool:
+def reinit_config_from_file(file_name: str, complete_config: bool = False) -> bool:
     file = Path(file_name)
     match file.suffix:
         case ".json":
@@ -314,6 +345,6 @@ def reinit_config_from_file(file_name: str) -> bool:
         logger.error(e)
         return False
 
-    reinit_config_from_dict(data)
+    reinit_config_from_dict(data, complete_config)
     logger.info(f"Load config from file: [{file}] success!")
     return True

asgi_webdav/constants.py

@@ -345,18 +345,25 @@ class DAVCompressLevel(Enum):
 
 # Authentication ---
 
-DEFAULT_HTTP_BASIC_AUTH_CACHE_TIMEOUT = (
-    -1
-)  # -1 means cache does not expire, 0 mean cache is disabled,
+DEFAULT_USERNAME = "username"
+DEFAULT_PASSWORD = "password"
+DEFAULT_USERNAME_ANONYMOUS = "anonymous"
+DEFAULT_PASSWORD_ANONYMOUS = ""
+DEFAULT_PERMISSIONS = ["+"]
+
+# -1 means cache does not expire, 0 mean cache is disabled,
 # >0 is seconds until cache entry expires
+DEFAULT_HTTP_BASIC_AUTH_CACHE_TIMEOUT = -1
 
 
 @dataclass
 class DAVUser:
     username: str
     password: str
     permissions: list[str]
+
     admin: bool
+    anonymous: bool = False
 
     permissions_allow: list[str] = field(default_factory=list)
     permissions_deny: list[str] = field(default_factory=list)

asgi_webdav/exception.py

@@ -1,8 +1,16 @@
+"""
+异常设计规则
+
+    - 以模块(逻辑概念的)做一级分割
+    - 如果需要再做二级分割
+"""
+
+
 class DAVException(Exception):
     pass
 
 
-class DAVExceptionConfigPaserFailed(DAVException):
+class DAVExceptionConfig(DAVException):
     pass
 
 

asgi_webdav/server.py

@@ -89,13 +89,17 @@ async def handle(
         # process WebDAV request
         try:
             response = await self.web_dav.distribute(request)
+            logger.debug(response)
 
         except DAVExceptionProviderInitFailed as e:
             logger.critical(e)
             logger.info(_service_abnormal_exit_message)
             sys.exit(1)
 
-        logger.debug(response)
+        if response.status == 401:
+            # TODO: 临时解决方案, 重构 DAVResponse 来统一 401 的响应行为
+            return request, self.dav_auth.create_response_401(request, "")
+
         return request, response
 
 

asgi_webdav/web_dav.py

@@ -208,7 +208,11 @@ async def distribute(self, request: DAVRequest) -> DAVResponse:
             if not request.user.check_paths_permission(paths):
                 # not allow
                 logger.debug(request)
-                return DAVResponse(status=403)
+                if request.user.anonymous:
+                    # is anonymous user
+                    return DAVResponse(status=401)
+                else:
+                    return DAVResponse(status=403)
 
         # update request distribute information
         request.update_distribute_info(provider.prefix)

docs/changelog.en.md

@@ -2,11 +2,11 @@
 
 ## 1.6.0
 
-- feat: new config, HTTPBasicAuth.cache_timeout
+- feat: new config, `HTTPBasicAuth.cache_timeout`
 - Optionally expire authentication cache entries after a defined time, thanks [PIC](https://www.pic.es)
-- feat: new config, Compression.enable
-- feat: both support .toml and .json config file
-- feat: support optional anonymous user, thanks [PIC](https://www.pic.es)
+- feat: new config, `Compression.enable`
+- feat: both support `.toml` and `.json` config file
+- feat: support optional anonymous user, thanks [PIC](https://www.pic.es)'s idea
 - feat: Implement a WebHDFS provider, contributed by [PIC](https://www.pic.es)
 
 ## 1.5.0 - 20250628