feat: support multi-suffix config files and switch default to TOML

Author: rexzhang

Dockerfile

@@ -6,7 +6,7 @@ ENV UID=1000
 ENV GID=1000
 ENV WEBDAV_HOST="0.0.0.0"
 ENV WEBDAV_PORT="8000"
-ENV WEBDAV_CONFIGFILE="/data/webdav.json"
+ENV WEBDAV_CONFIGFILE="/data/webdav.toml"
 ENV WEBDAV_LOGGING_LEVEL="INFO"
 
 RUN if [ "$BUILD_DEV" = "rex" ]; then echo "Change depends" \

TODO

@@ -1,5 +1,5 @@
 进行中:
-    ☐ 匿名账号支持
+    ✔ 匿名账号支持 @done(25-10-30)
         ✔ 重新设计 Config 部分 @done(25-10-08)
         ✔ 匿名账号在账号清单中生效 @done(25-10-19)
         ✔ 匿名账号能通过 HTTP Auth 登录 @done(25-10-19)
@@ -11,7 +11,13 @@
         TOML 作为配置文件的第一格式
         ✔ pydantic => dataclass @done
         ✔ 添加 TOML 支持 @done
-        ☐ 使用 TOML 方便方便添加注释的特性增加各种使用场景配置范例 @long-term
+        ✔ docker 环境支持自动尝试多种配置文件后缀 @done(25-10-31)
+            ✔ 默认配置文件改为 webdav.toml @done(25-10-31)
+        ☐ 自动尝试多种配置文件后缀这个行为通过命令行打开,默认不开启
+        ☐ 通过配置文件实现 dev 模式的切换
+        ☐ 通过配置文件实现 litmus 模式的切换 @wip
+        ☐ 更新文档 @wip
+        ☐ 使用 TOML 方便添加注释的特性, 增加各种使用场景配置范例 @long-term
         ☐ 以 TOML 下的可读性为标准,适当调整配置文件结构 @long-term
 
 长期性任务:
@@ -31,12 +37,15 @@
         ☐ 文档自动部署失效问题
 
 待实现:
+    ☐ 兼容 Py3.14
     ☐ 重构 DAVResponse 来统一 401 的响应行为 @high @next-release
         ☐ 浏览器请求才弹认证请求框, 服务器返回 401 时不弹认证框
         ☐ 重构部分 DAVResponse 代码, 这个与压缩依赖部分一起修改
         ☐ 顺带解决 litmus 的一个告警?
-    ☐ 移除第三方压缩依赖,添加sztd支持 @delay dataclass-wizard 不兼容 py3.14
-    ☐ Digest auth support neon @low @@deplay 需要时间过多
+    ☐ 移除第三方压缩依赖,添加sztd支持 @block dataclass-wizard 不兼容 py3.14
+    ☐ 更新 xmltodict 到最新版本
+        这个上游库变化非常大, 之前版本与现在版本不兼容
+    ☐ Digest auth support neon @deplay 需要时间过多
 
 待确定实现方案:
     ☐ 统一 user/account 的概念 @low
@@ -53,5 +62,6 @@
 
 待确定可行性:
     ☐ generate random URL for share(read only) @high
+        `/_/share/ + random string`
     ☐ rewrite MemoryProvider with mmap or other
     ☐ logout at the web page

asgi_webdav/cli.py

@@ -56,7 +56,7 @@ def convert_click_kwargs_to_aep(kwargs: dict) -> AppEntryParameters:
     "-c",
     "--config",
     default=None,
-    help="Load configuration from file.  [default: None]",
+    help="Load configuration from file, support .toml/.json  [default: None]",
 )
 @click.option(
     "-u",

asgi_webdav/config.py

@@ -25,6 +25,7 @@
     AppEntryParameters,
     DAVCompressLevel,
 )
+from asgi_webdav.exception import DAVExceptionConfigFileNotFound
 
 logger = getLogger(__name__)
 
@@ -337,7 +338,8 @@ def reinit_config_from_file(file_name: str, complete_config: bool = False) -> bo
         message = f"Can not open config file[{file}]!"
         logger.error(message)
         logger.error(e)
-        return False
+        # return False
+        raise DAVExceptionConfigFileNotFound(e)
 
     except (json.JSONDecodeError, tomllib.TOMLDecodeError) as e:
         message = f"Load config from file[{file}] failed!"
@@ -348,3 +350,32 @@ def reinit_config_from_file(file_name: str, complete_config: bool = False) -> bo
     reinit_config_from_dict(data, complete_config)
     logger.info(f"Load config from file: [{file}] success!")
     return True
+
+
+def reinit_config_from_file_multi_suffix(
+    file_name: str, complete_config: bool = False
+) -> bool:
+    """help users in switching from .json to .toml configuration files."""
+
+    try:
+        return reinit_config_from_file(file_name, complete_config)
+    except DAVExceptionConfigFileNotFound:
+        logger.warning(f"Can not found config file: {file_name}!")
+
+    # try other suffix
+    file = Path(file_name)
+    stem = file.stem
+    suffix = file.suffix
+
+    suffixs = {".json", ".toml"}
+    suffixs.remove(suffix)
+
+    for suffix in suffixs:
+        file_name = f"{stem}{suffix}"
+        logger.warning(f"Try load config file: {file_name}!")
+        try:
+            return reinit_config_from_file(file_name, complete_config)
+        except DAVExceptionConfigFileNotFound:
+            logger.warning(f"Can not found config file: {file_name}!")
+
+    return False

asgi_webdav/exception.py

@@ -14,6 +14,10 @@ class DAVExceptionConfig(DAVException):
     pass
 
 
+class DAVExceptionConfigFileNotFound(DAVExceptionConfig):
+    pass
+
+
 class DAVExceptionRequestParserFailed(DAVException):
     pass
 

asgi_webdav/server.py

@@ -13,7 +13,7 @@
     Config,
     get_config,
     reinit_config_from_dict,
-    reinit_config_from_file,
+    reinit_config_from_file_multi_suffix,
 )
 from asgi_webdav.constants import AppEntryParameters, DAVMethod, DevMode
 from asgi_webdav.exception import DAVExceptionProviderInitFailed
@@ -109,7 +109,7 @@ def get_asgi_app(aep: AppEntryParameters, config_obj: dict | None = None):
 
     # init config
     if aep.config_file is not None:
-        reinit_config_from_file(aep.config_file)
+        reinit_config_from_file_multi_suffix(aep.config_file)
     elif config_obj is not None:
         reinit_config_from_dict(config_obj)
 

docs/compatibility.en.md

@@ -34,7 +34,9 @@ litmus http://IPAddress:8000/provider/memory username password
 - Version: 1.3.2
 
 ```shell
-python -m asgi_webdav --litmus
+python -m asgi_webdav -c examples/config/litmus.toml -H 0.0.0.0
+# or
+python -m asgi_webdav --litmus # Deprecated
 ```
 
 ```text

docs/reference/config-file.en.md

@@ -1,10 +1,14 @@
 # Config File
 
-## `webdav.json` file
+## `webdav.toml` file
+
+### Convert `.json` to `.toml`
+
+please search `convert json toml` in your browser.
 
 ### When the file does not exist
 
-When the file `/data/webdav.json` does not exist, `http://127.0.0.1/` will map to the `/data` directory.
+When the file `/data/webdav.toml(.json)` does not exist, `http://127.0.0.1/` will map to the `/data` directory.
 
 #### logging output
 
@@ -21,62 +25,54 @@ INFO: [uvicorn] Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
 
 When the file exists, the mapping relationship is defined by the file content.
 
-#### Sample
-
-```json
-{
-  "account_mapping": [
-    {
-      "username": "username",
-      "password": "password",
-      "permissions": ["+"]
-    },
-    {
-      "username": "litmus",
-      "password": "password",
-      "permissions": ["+^/$", "+^/litmus", "-^/litmus/other"]
-    },
-    {
-      "username": "guest",
-      "password": "password",
-      "permissions": []
-    }
-  ],
-  "anonymous": { "enable": true },
-  "http_basic_auth": {
-    "cache_type": "expiring",
-    "cache_timeout": 3600
-  },
-  "provider_mapping": [
-    {
-      "prefix": "/",
-      "uri": "file:///data/root",
-      "read_only": true
-    },
-    {
-      "prefix": "/provider",
-      "uri": "memory:///",
-      "read_only": true
-    },
-    {
-      "prefix": "/provider/fs",
-      "uri": "file:///data/litmus"
-    },
-    {
-      "prefix": "/provider/memory",
-      "uri": "memory:///",
-      "ignore_property_extra": false
-    },
-    {
-      "prefix": "/~",
-      "uri": "file:///data/home",
-      "home_dir": true
-    }
-  ],
-  "logging_level": "INFO"
-}
+#### Example
+
+```toml
+[[account_mapping]]
+username = "username"
+password = "password"
+permissions = [ "+" ]
+
+[[account_mapping]]
+username = "litmus"
+password = "password"
+permissions = [ "+^/$", "+^/litmus", "-^/litmus/other" ]
+
+[[account_mapping]]
+username = "guest"
+password = "password"
+permissions = [ ]
+
+[anonymous]
+enable = true
+
+[[provider_mapping]]
+prefix = "/"
+uri = "file:///data/root"
+read_only = true
+
+[[provider_mapping]]
+prefix = "/provider"
+uri = "memory:///"
+read_only = true
+
+[[provider_mapping]]
+prefix = "/provider/fs"
+uri = "file:///data/litmus"
+
+[[provider_mapping]]
+prefix = "/provider/memory"
+uri = "memory:///"
+ignore_property_extra = false
+
+[[provider_mapping]]
+prefix = "/~"
+uri = "file:///data/home"
+home_dir = true
 ```
 
+More example please check `examples/config/*.toml` in codebase.
+
 #### logging output
 
 ```text
@@ -112,24 +108,9 @@ root object
 | text_file_charset_detect | rules    | `TextFileCharsetDetect` | `TextFileCharsetDetect()` |
 | compression              | response | `Compression`           | `Compression()`           |
 | cors                     | response | `CORS`                  | `CORS()`                  |
-| logging_level            | other    | `str`                   | `"INFO"`                  |
-
-Example
-
-```text
-{
-  "account_mapping": [...],
-  "anonymous": {...},
-  "http_digest_auth": {...},
-  "provider_mapping": [...],
-  "hide_file_in_dir": {...},
-  "guess_type_extension": {...},
-  "text_file_charset_detect": {...},
-  "compression": {...},
-  "cors": {...},
-  "logging_level": "INFO"
-}
-```
+| enable_dir_browser       | response | `bool`                  | `true`                    |
+| logging                  | other    | `Logging`               | `"Logging()"`             |
+| sentry_dsn               | other    | `str`                   | `None`                    |
 
 ## for Authentication
 
@@ -330,3 +311,15 @@ More detail, please see howto.
 | allow_credentials  | bool       | `false`       | -                                                       |
 | expose_headers     | list[str]  | `[]`          | -                                                       |
 | preflight_max_age  | int        | `600`         | -                                                       |
+
+### `logging` Object
+
+- Introduced in 1.4
+- Last updated in 1.4
+
+| Key              | Value Type | Default Value |
+| ---------------- | ---------- | ------------- |
+| enable           | bool       | `true`        |
+| level            | str        | `"INFO"`      |
+| display_datetime | bool       | `true`        |
+| use_colors       | bool       | `true`        |

docs/reference/env-value.en.md

@@ -14,4 +14,4 @@
 | ----------------- | ------------------- |
 | WEBDAV_HOST       | `0.0.0.0`           |
 | WEBDAV_PORT       | `8000`              |
-| WEBDAV_CONFIGFILE | `/data/webdav.json` |
+| WEBDAV_CONFIGFILE | `/data/webdav.toml` |

examples/config/litmus.toml

@@ -0,0 +1,27 @@
+[[account_mapping]]
+username = "username"
+password = "password"
+permissions = ["+"]
+admin = true
+
+[[provider_mapping]]
+uri = "memory:///"
+prefix = "/"
+read_only = true
+ignore_property_extra = false
+
+[[provider_mapping]]
+prefix = "/provider"
+uri = "memory:///"
+read_only = true
+ignore_property_extra = false
+
+[[provider_mapping]]
+prefix = "/provider/fs"
+uri = "file:///tmp"
+ignore_property_extra = false
+
+[[provider_mapping]]
+prefix = "/provider/memory"
+uri = "memory:///"
+ignore_property_extra = false