ddns 4.1.0b1__py2.py3-none-any.whl → 4.1.0b2__py2.py3-none-any.whl

ddns/provider/_base.py

@@ -1,20 +1,18 @@
 # coding=utf-8
 """
 ## SimpleProvider 简单DNS抽象基类
-
 * set_record()
 
 ## BaseProvider 标准DNS抽象基类
 定义所有 DNS 服务商 API 类应继承的抽象基类，统一接口，便于扩展适配多服务商。
-
-Abstract base class for DNS provider APIs.
 Defines a unified interface to support extension and adaptation across providers.
 * _query_zone_id
 * _query_record
 * _update_record
 * _create_record
+
 ┌──────────────────────────────────────────────────┐
-│        用户调用 set_record(domain, value...)      │
+│          调用 set_record(domain, value...)        │
 └──────────────────────────────────────────────────┘
                       │
                       ▼
@@ -58,121 +56,30 @@ Defines a unified interface to support extension and adaptation across providers
 """
 
 from abc import ABCMeta, abstractmethod
-from hashlib import sha256
-from hmac import HMAC
 from json import loads as jsondecode, dumps as jsonencode
 from logging import Logger, getLogger  # noqa:F401 # type: ignore[no-redef]
-from os import environ
-from ..util.http import send_http_request
-
-try:  # python 3
-    from urllib.parse import quote, urlencode
-except ImportError:  # python 2
-    from urllib import urlencode, quote  # type: ignore[no-redef,import-untyped]
+from ..util.http import send_http_request, quote, urlencode
 
 TYPE_FORM = "application/x-www-form-urlencoded"
 TYPE_JSON = "application/json"
 
 
-def hmac_sha256(key, message):
-    # type: (str | bytes, str | bytes) -> HMAC
-    """
-    计算 HMAC-SHA256 签名对象
-
-    Compute HMAC-SHA256 signature object.
-
-    Args:
-        key (str | bytes): 签名密钥 / Signing key
-        message (str | bytes): 待签名消息 / Message to sign
-
-    Returns:
-        HMAC: HMAC签名对象，可调用.digest()获取字节或.hexdigest()获取十六进制字符串
-              HMAC signature object, call .digest() for bytes or .hexdigest() for hex string
-    """
-    # Python 2/3 compatible encoding - avoid double encoding in Python 2
-    if not isinstance(key, bytes):
-        key = key.encode("utf-8")
-    if not isinstance(message, bytes):
-        message = message.encode("utf-8")
-    return HMAC(key, message, sha256)
-
-
-def sha256_hash(data):
-    # type: (str | bytes) -> str
+def encode_params(params):
+    # type: (dict|list|str|bytes|None) -> str
     """
-    计算 SHA256 哈希值
-
-    Compute SHA256 hash.
+    编码参数为 URL 查询字符串,参数顺序会排序
 
     Args:
-        data (str | bytes): 待哈希数据 / Data to hash
-
+        params (dict|list|str|bytes|None): 参数字典、列表或字符串
     Returns:
-        str: 十六进制哈希字符串 / Hexadecimal hash string
+        str: 编码后的查询字符串
     """
-    # Python 2/3 compatible encoding - avoid double encoding in Python 2
-    if not isinstance(data, bytes):
-        data = data.encode("utf-8")
-    return sha256(data).hexdigest()
-
-
-def hmac_sha256_authorization(
-    secret_key,  # type: str | bytes
-    method,  # type: str
-    path,  # type: str
-    query,  # type: str
-    headers,  # type: dict[str, str]
-    body_hash,  # type: str
-    signing_string_format,  # type: str
-    authorization_format,  # type: str
-):
-    # type: (...) -> str
-    """
-    HMAC-SHA256 云服务商通用认证签名生成器
-
-    Universal cloud provider authentication signature generator using HMAC-SHA256.
-
-    通用的云服务商API认证签名生成函数，使用HMAC-SHA256算法生成符合各云服务商规范的Authorization头部。
-
-    模板变量格式：{HashedCanonicalRequest}, {SignedHeaders}, {Signature}
-
-    Args:
-        secret_key (str | bytes): 签名密钥，已经过密钥派生处理 / Signing key (already derived if needed)
-        method (str): HTTP请求方法 / HTTP request method (GET, POST, etc.)
-        path (str): API请求路径 / API request path
-        query (str): URL查询字符串 / URL query string
-        headers (dict[str, str]): HTTP请求头部 / HTTP request headers
-        body_hash (str): 请求体的SHA256哈希值 / SHA256 hash of request payload
-        signing_string_format (str): 待签名字符串模板，包含 {HashedCanonicalRequest} 占位符
-        authorization_format (str): Authorization头部模板，包含 {SignedHeaders}, {Signature} 占位符
-
-    Returns:
-        str: 完整的Authorization头部值 / Complete Authorization header value
-    """
-    # 1. 构建规范化头部 - 所有传入的头部都参与签名
-    headers_to_sign = {k.lower(): str(v).strip() for k, v in headers.items()}
-    signed_headers_list = sorted(headers_to_sign.keys())
-
-    # 2. 构建规范请求字符串
-    canonical_headers = ""
-    for header_name in signed_headers_list:
-        canonical_headers += "{}:{}\n".format(header_name, headers_to_sign[header_name])
-
-    # 构建完整的规范请求字符串
-    signed_headers = ";".join(signed_headers_list)
-    canonical_request = "\n".join([method.upper(), path, query, canonical_headers, signed_headers, body_hash])
-
-    # 3. 构建待签名字符串 - 只需要替换 HashedCanonicalRequest
-    hashed_canonical_request = sha256_hash(canonical_request)
-    string_to_sign = signing_string_format.format(HashedCanonicalRequest=hashed_canonical_request)
-
-    # 4. 计算最终签名
-    signature = hmac_sha256(secret_key, string_to_sign).hexdigest()
-
-    # 5. 构建Authorization头部 - 只需要替换 SignedHeaders 和 Signature
-    authorization = authorization_format.format(SignedHeaders=signed_headers, Signature=signature)
-
-    return authorization
+    if not params:
+        return ""
+    elif isinstance(params, (str, bytes)):
+        return params  # type: ignore[return-value]
+    items = params.items() if isinstance(params, dict) else params
+    return urlencode(sorted(items), doseq=True)
 
 
 class SimpleProvider(object):
@@ -188,43 +95,43 @@ class SimpleProvider(object):
     __metaclass__ = ABCMeta
 
     # API endpoint domain (to be defined in subclass)
-    API = ""  # type: str # https://exampledns.com
+    endpoint = ""  # type: str # https://exampledns.com
     # Content-Type for requests (to be defined in subclass)
     content_type = TYPE_FORM  # type: Literal["application/x-www-form-urlencoded"] | Literal["application/json"]
     # 默认 accept 头部, 空则不设置
     accept = TYPE_JSON  # type: str | None
     # Decode Response as JSON by default
-    decode_response = True
-    # 是否验证 SSL 证书，默认为 True
-    verify_ssl = "auto"  # type: bool | str
-
-    # 版本
-    version = environ.get("DDNS_VERSION", "0.0.0")
+    decode_response = True  # type: bool
+    # UA 可自定义, 可在子类中覆盖，空则不设置
+    user_agent = "DDNS/{version} (ddns@newfuture.cc)"
     # Description
-    remark = "Managed by [DDNS v{}](https://ddns.newfuture.cc)".format(version)
+    remark = "Managed by [DDNS](https://ddns.newfuture.cc)"
 
-    def __init__(self, auth_id, auth_token, logger=None, verify_ssl=None, **options):
-        # type: (str, str, Logger | None, bool|str| None, **object) -> None
+    def __init__(self, id, token, logger=None, verify_ssl="auto", proxy=None, endpoint=None, **options):
+        # type: (str, str, Logger | None, bool|str, Sequence[str|None]|None, str|None, **object) -> None
         """
         初始化服务商对象
 
         Initialize provider instance.
 
         Args:
-            auth_id (str): 身份认证 ID / Authentication ID
-            auth_token (str): 密钥 / Authentication Token
-            options (dict): 其它参数，如代理、调试等 / Additional options
+            id (str): 身份认证 ID / Authentication ID
+            token (str): 密钥 / Authentication Token
+            options (dict): 其它参数 / Additional options
         """
-        self.auth_id = auth_id  # type: str
-        self.auth_token = auth_token  # type: str
+        self.id = id
+        self.token = token
+        if endpoint:
+            self.endpoint = endpoint
+        self._proxy = proxy if proxy and len(proxy) else [None]
+        self._ssl = verify_ssl
+
         self.options = options
         name = self.__class__.__name__
         self.logger = (logger or getLogger()).getChild(name)
-        self.proxy = None  # type: str | None
-        if verify_ssl is not None:
-            self.verify_ssl = verify_ssl
+
         self._zone_map = {}  # type: dict[str, str]
-        self.logger.debug("%s initialized with: %s", self.__class__.__name__, auth_id)
+        self.logger.debug("%s initialized with: %s", self.__class__.__name__, id)
         self._validate()  # 验证身份认证信息
 
     @abstractmethod
@@ -248,22 +155,6 @@ class SimpleProvider(object):
         """
         raise NotImplementedError("This set_record should be implemented by subclasses")
 
-    def set_proxy(self, proxy_str):
-        # type: (str | None) -> SimpleProvider
-        """
-        设置代理服务器
-
-        Set HTTPS proxy string.
-
-        Args:
-            proxy_str (str): 代理地址
-
-        Returns:
-            Self: 自身
-        """
-        self.proxy = proxy_str
-        return self
-
     def _validate(self):
         # type: () -> None
         """
@@ -271,11 +162,11 @@ class SimpleProvider(object):
 
         Validate authentication credentials.
         """
-        if not self.auth_id:
+        if not self.id:
             raise ValueError("id must be configured")
-        if not self.auth_token:
+        if not self.token:
             raise ValueError("token must be configured")
-        if not self.API:
+        if not self.endpoint:
             raise ValueError("API endpoint must be defined in {}".format(self.__class__.__name__))
 
     def _http(self, method, url, params=None, body=None, queries=None, headers=None):  # noqa: C901
@@ -314,13 +205,13 @@ class SimpleProvider(object):
 
         # 构建查询字符串
         if len(query_params) > 0:
-            url += ("&" if "?" in url else "?") + self._encode(query_params)
+            url += ("&" if "?" in url else "?") + encode_params(query_params)
 
         # 构建完整URL
         if not url.startswith("http://") and not url.startswith("https://"):
-            if not url.startswith("/") and self.API.endswith("/"):
+            if not url.startswith("/") and self.endpoint.endswith("/"):
                 url = "/" + url
-            url = self.API + url
+            url = self.endpoint + url
 
         # 记录请求日志
         self.logger.info("%s %s", method, self._mask_sensitive_data(url))
@@ -330,30 +221,32 @@ class SimpleProvider(object):
         if body:
             if "content-type" not in headers:
                 headers["content-type"] = self.content_type
-            if isinstance(body, (str, bytes)):
-                body_data = body
-            elif self.content_type == TYPE_FORM:
-                body_data = self._encode(body)
-            else:
-                body_data = jsonencode(body)
+            body_data = self._encode_body(body)
             self.logger.debug("body:\n%s", self._mask_sensitive_data(body_data))
 
         # 处理headers
         if self.accept and "accept" not in headers and "Accept" not in headers:
             headers["accept"] = self.accept
-        if len(headers) > 2:
+        if "user-agent" not in headers and "User-Agent" not in headers and self.user_agent:
+            headers["user-agent"] = self.user_agent
+        if len(headers) > 3:
             self.logger.debug("headers:\n%s", {k: self._mask_sensitive_data(v) for k, v in headers.items()})
 
-        response = send_http_request(
-            url=url,
-            method=method,
-            body=body_data,
-            headers=headers,
-            proxy=self.proxy,
-            max_redirects=5,
-            verify_ssl=self.verify_ssl,
-        )
-
+        response = None  # type: Any
+        for p in self._proxy:
+            if p:
+                self.logger.debug("Using proxy: %s", p)
+            try:
+                response = send_http_request(
+                    method, url, body=body_data, headers=headers, proxy=p, verify_ssl=self._ssl
+                )
+                break  # 成功发送请求，跳出循环
+            except Exception as e:
+                self.logger.warning("Failed to send request: %s", e)
+        if not response:
+            if len(self._proxy) > 1:
+                self.logger.error("Failed to send request via all proxies: %s", self._proxy)
+            raise RuntimeError("Failed to send request to {}".format(url))
         # 处理响应
         status_code = response.status
         if not (200 <= status_code < 300):
@@ -368,7 +261,7 @@ class SimpleProvider(object):
             elif status_code == 401:
                 raise RuntimeError("认证失败 [401]: " + response.reason)
             elif status_code == 403:
-                raise RuntimeError("权限不足 [403]: " + response.reason)
+                raise RuntimeError("禁止访问 [403]: " + response.reason)
             else:
                 raise RuntimeError("服务器错误 [{}]: {}".format(status_code, response.reason))
 
@@ -382,36 +275,23 @@ class SimpleProvider(object):
             self.logger.error("fail to decode response: %s", e)
         return res
 
-    @staticmethod
-    def _encode(params):
-        # type: (dict|list|str|bytes|None) -> str
+    def _encode_body(self, data):
+        # type: (dict | list | str | bytes | None) -> str
         """
-        编码参数为 URL 查询字符串
-
+        自动编码数据为字符串或字节, 根据 content_type 选择编码方式。
         Args:
-            params (dict|list|str|bytes|None): 参数字典、列表或字符串
-        Returns:
-            str: 编码后的查询字符串
-        """
-        if not params:
-            return ""
-        elif isinstance(params, (str, bytes)):
-            return params  # type: ignore[return-value]
-        return urlencode(params, doseq=True)
-
-    @staticmethod
-    def _quote(data, safe="/"):
-        # type: (str, str) -> str
-        """
-        对字符串进行 URL 编码
-
-        Args:
-            data (str): 待编码字符串
+            data (dict | list | str | bytes | None): 待编码数据
 
         Returns:
-            str: 编码后的字符串
+            str | bytes | None: 编码后的数据
         """
-        return quote(data, safe=safe)
+        if isinstance(data, (str, bytes)):
+            return data  # type: ignore[return-value]
+        if not data:
+            return ""
+        if self.content_type == TYPE_FORM:
+            return encode_params(data)
+        return jsonencode(data)
 
     def _mask_sensitive_data(self, data):
         # type: (str | bytes | None) -> str | bytes | None
@@ -423,19 +303,19 @@ class SimpleProvider(object):
         Returns:
             str | bytes | None: 打码后的字符串
         """
-        if not data or not self.auth_token:
+        if not data or not self.token:
             return data
 
         # 生成打码后的token
-        token_masked = self.auth_token[:2] + "***" + self.auth_token[-2:] if len(self.auth_token) > 4 else "***"
-        token_encoded = quote(self.auth_token, safe="")
+        token_masked = self.token[:2] + "***" + self.token[-2:] if len(self.token) > 4 else "***"
+        token_encoded = quote(self.token, safe="")
 
         if isinstance(data, bytes):  # 处理字节数据
-            return data.replace(self.auth_token.encode(), token_masked.encode()).replace(
+            return data.replace(self.token.encode(), token_masked.encode()).replace(
                 token_encoded.encode(), token_masked.encode()
             )
         if hasattr(data, "replace"):  # 处理字符串数据
-            return data.replace(self.auth_token, token_masked).replace(token_encoded, token_masked)
+            return data.replace(self.token, token_masked).replace(token_encoded, token_masked)
         return data
 
 
@@ -472,7 +352,7 @@ class BaseProvider(SimpleProvider):
         """
         domain = domain.lower()
         self.logger.info("%s => %s(%s)", domain, value, record_type)
-        sub, main = split_custom_domain(domain)
+        sub, main = _split_custom_domain(domain)
         try:
             if sub is not None:
                 # 使用自定义分隔符格式
@@ -619,7 +499,7 @@ class BaseProvider(SimpleProvider):
         return None, None, main
 
 
-def split_custom_domain(domain):
+def _split_custom_domain(domain):
     # type: (str) -> tuple[str | None, str]
     """
     拆分支持 ~ 或 + 的自定义格式域名为 (子域, 主域)

ddns/provider/_signature.py

@@ -0,0 +1,113 @@
+# coding=utf-8
+"""
+DNS Provider 签名和哈希算法模块
+
+Signature and hash algorithms module for DNS providers.
+Provides common cryptographic functions for cloud provider authentication.
+
+@author: NewFuture
+"""
+
+from hashlib import sha256
+from hmac import HMAC
+
+
+def hmac_sha256(key, message):
+    # type: (str | bytes, str | bytes) -> HMAC
+    """
+    计算 HMAC-SHA256 签名对象
+
+    Compute HMAC-SHA256 signature object.
+
+    Args:
+        key (str | bytes): 签名密钥 / Signing key
+        message (str | bytes): 待签名消息 / Message to sign
+
+    Returns:
+        HMAC: HMAC签名对象，可调用.digest()获取字节或.hexdigest()获取十六进制字符串
+              HMAC signature object, call .digest() for bytes or .hexdigest() for hex string
+    """
+    # Python 2/3 compatible encoding - avoid double encoding in Python 2
+    if not isinstance(key, bytes):
+        key = key.encode("utf-8")
+    if not isinstance(message, bytes):
+        message = message.encode("utf-8")
+    return HMAC(key, message, sha256)
+
+
+def sha256_hash(data):
+    # type: (str | bytes) -> str
+    """
+    计算 SHA256 哈希值
+
+    Compute SHA256 hash.
+
+    Args:
+        data (str | bytes): 待哈希数据 / Data to hash
+
+    Returns:
+        str: 十六进制哈希字符串 / Hexadecimal hash string
+    """
+    # Python 2/3 compatible encoding - avoid double encoding in Python 2
+    if not isinstance(data, bytes):
+        data = data.encode("utf-8")
+    return sha256(data).hexdigest()
+
+
+def hmac_sha256_authorization(
+    secret_key,  # type: str | bytes
+    method,  # type: str
+    path,  # type: str
+    query,  # type: str
+    headers,  # type: dict[str, str]
+    body_hash,  # type: str
+    signing_string_format,  # type: str
+    authorization_format,  # type: str
+):
+    # type: (...) -> str
+    """
+    HMAC-SHA256 云服务商通用认证签名生成器
+
+    Universal cloud provider authentication signature generator using HMAC-SHA256.
+
+    通用的云服务商API认证签名生成函数，使用HMAC-SHA256算法生成符合各云服务商规范的Authorization头部。
+
+    模板变量格式：{HashedCanonicalRequest}, {SignedHeaders}, {Signature}
+
+    Args:
+        secret_key (str | bytes): 签名密钥，已经过密钥派生处理 / Signing key (already derived if needed)
+        method (str): HTTP请求方法 / HTTP request method (GET, POST, etc.)
+        path (str): API请求路径 / API request path
+        query (str): URL查询字符串 / URL query string
+        headers (dict[str, str]): HTTP请求头部 / HTTP request headers
+        body_hash (str): 请求体的SHA256哈希值 / SHA256 hash of request payload
+        signing_string_format (str): 待签名字符串模板，包含 {HashedCanonicalRequest} 占位符
+        authorization_format (str): Authorization头部模板，包含 {SignedHeaders}, {Signature} 占位符
+
+    Returns:
+        str: 完整的Authorization头部值 / Complete Authorization header value
+    """
+    # 1. 构建规范化头部 - 所有传入的头部都参与签名
+    headers_to_sign = {k.lower(): str(v).strip() for k, v in headers.items()}
+    signed_headers_list = sorted(headers_to_sign.keys())
+
+    # 2. 构建规范请求字符串
+    canonical_headers = ""
+    for header_name in signed_headers_list:
+        canonical_headers += "{}:{}\n".format(header_name, headers_to_sign[header_name])
+
+    # 构建完整的规范请求字符串
+    signed_headers = ";".join(signed_headers_list)
+    canonical_request = "\n".join([method.upper(), path, query, canonical_headers, signed_headers, body_hash])
+
+    # 3. 构建待签名字符串 - 只需要替换 HashedCanonicalRequest
+    hashed_canonical_request = sha256_hash(canonical_request)
+    string_to_sign = signing_string_format.format(HashedCanonicalRequest=hashed_canonical_request)
+
+    # 4. 计算最终签名
+    signature = hmac_sha256(secret_key, string_to_sign).hexdigest()
+
+    # 5. 构建Authorization头部 - 只需要替换 SignedHeaders 和 Signature
+    authorization = authorization_format.format(SignedHeaders=signed_headers, Signature=signature)
+
+    return authorization

ddns/provider/alidns.py

@@ -5,25 +5,37 @@ AliDNS API
 @author: NewFuture
 """
 
-from ._base import TYPE_FORM, BaseProvider, hmac_sha256_authorization, sha256_hash, join_domain
+from ._base import TYPE_FORM, BaseProvider, join_domain, encode_params
+from ._signature import hmac_sha256_authorization, sha256_hash
 from time import strftime, gmtime, time
 
 
-class AlidnsProvider(BaseProvider):
-    API = "https://alidns.aliyuncs.com"
-    content_type = TYPE_FORM  # 阿里云DNS API使用表单格式
+class AliBaseProvider(BaseProvider):
+    """阿里云基础Provider，提供通用的_request方法"""
 
+    endpoint = "https://alidns.aliyuncs.com"
+    content_type = TYPE_FORM  # 阿里云DNS API使用表单格式
     api_version = "2015-01-09"  # API版本，v3签名需要
 
-    def _request(self, action, **params):
-        # type: (str, **(str | int | bytes | bool | None)) -> dict
+    def _request(self, action, method="POST", **params):
+        # type: (str, str, **(Any)) -> dict
         """Aliyun v3 https://help.aliyun.com/zh/sdk/product-overview/v3-request-structure-and-signature"""
         params = {k: v for k, v in params.items() if v is not None}
-        body_content = self._encode(params) if len(params) > 0 else ""
+
+        if method in ("GET", "DELETE"):
+            # For GET and DELETE requests, parameters go in query string
+            query_string = encode_params(params) if len(params) > 0 else ""
+            body_content = ""
+        else:
+            # For POST requests, parameters go in body
+            body_content = self._encode_body(params)
+            query_string = ""
+
+        path = "/"
         content_hash = sha256_hash(body_content)
         # 构造请求头部
         headers = {
-            "host": self.API.split("://", 1)[1].strip("/"),
+            "host": self.endpoint.split("://", 1)[1].strip("/"),
             "content-type": self.content_type,
             "x-acs-action": action,
             "x-acs-content-sha256": content_hash,
@@ -34,20 +46,25 @@ class AlidnsProvider(BaseProvider):
 
         # 使用通用签名函数
         authorization = hmac_sha256_authorization(
-            secret_key=self.auth_token,
-            method="POST",
-            path="/",
-            query="",
+            secret_key=self.token,
+            method=method,
+            path=path,
+            query=query_string,
             headers=headers,
             body_hash=content_hash,
             signing_string_format="ACS3-HMAC-SHA256\n{HashedCanonicalRequest}",
             authorization_format=(
-                "ACS3-HMAC-SHA256 Credential=" + self.auth_id + ",SignedHeaders={SignedHeaders},Signature={Signature}"
+                "ACS3-HMAC-SHA256 Credential=" + self.id + ",SignedHeaders={SignedHeaders},Signature={Signature}"
             ),
         )
         headers["Authorization"] = authorization
         # 对于v3签名的RPC API，参数在request body中
-        return self._http("POST", "/", body=body_content, headers=headers)
+        path = path if not query_string else path + "?" + format(query_string)
+        return self._http(method, path, body=body_content, headers=headers)
+
+
+class AlidnsProvider(AliBaseProvider):
+    """阿里云DNS Provider"""
 
     def _split_zone_and_sub(self, domain):
         # type: (str) -> tuple[str | None, str | None, str]