Development Guide: How to Implement a New DNS Provider

This guide explains how to quickly implement a custom DNS provider adapter class based on different abstract base classes to support dynamic DNS record creation and updates.

📦 Directory Structure

text

ddns/
├── provider/
│   ├── _base.py         # Abstract base classes SimpleProvider and BaseProvider, signature auth functions
│   └── myprovider.py    # Your new provider implementation
tests/
├── base_test.py         # Shared test utilities and base classes
├── test_provider_*.py   # Provider-specific test files
├── test_module_*.py     # Other tests
└── README.md            # Testing guide
doc/dev/
└── provider.md          # Provider development guide (this document)

🚀 Quick Start

DDNS provides two abstract base classes. Choose the appropriate base class based on your DNS provider's API characteristics:

1. SimpleProvider - Simple DNS Provider

Suitable for DNS providers that only offer simple update interfaces without support for querying existing records.

Required Methods:

Method	Description	Required
`set_record(domain, value, record_type="A", ttl=None, line=None, **extra)`	Update or create DNS record	✅ Required
`_validate()`	Validate authentication info	❌ Optional (has default implementation)

Use Cases:

DNS providers that only offer update interfaces (like HE.net)
Simple scenarios that don't need to query existing records
Debugging and testing purposes
Callback/Webhook type DNS updates

2. BaseProvider - Full DNS Provider ⭐️ Recommended

Suitable for standard DNS provider APIs that offer complete CRUD operations.

Required Methods:

Method	Description	Required
`_query_zone_id(domain)`	Query zone ID for main domain	✅ Required
`_query_record(zone_id, subdomain, main_domain, record_type, line=None, extra=None)`	Query current DNS record	✅ Required
`_create_record(zone_id, subdomain, main_domain, value, record_type, ttl=None, line=None, extra=None)`	Create new record	✅ Required
`_update_record(zone_id, old_record, value, record_type, ttl=None, line=None, extra=None)`	Update existing record	✅ Required
`_validate()`	Validate authentication info	❌ Optional (default requires id and token)

Built-in Features:

✅ All SimpleProvider functionality
🎯 Automatic record management (complete query→create/update workflow)
💾 Caching mechanism
📝 Detailed operation logging and error handling

Use Cases:

DNS providers with complete REST APIs (like Cloudflare, Alibaba Cloud DNS)
Scenarios requiring query of existing record status
Support for precise record management and status tracking

🔧 Implementation Examples

SimpleProvider Example

Suitable for simple DNS providers, refer to existing implementations:

provider/he.py: Hurricane Electric DNS updates
provider/debug.py: Debugging purposes, prints IP addresses
provider/callback.py: Callback/Webhook type DNS updates

provider/mysimpleprovider.py

python

# coding=utf-8
"""
Custom simple DNS provider example
@author: YourGithubUsername
"""
from ._base import SimpleProvider, TYPE_FORM

class MySimpleProvider(SimpleProvider):
    """
    Example SimpleProvider implementation
    Supports simple DNS record updates, suitable for most simple DNS APIs
    """
    API = 'https://api.simpledns.com'
    content_type = TYPE_FORM          # or TYPE_JSON
    decode_response = False           # Set to False if returns plain text instead of JSON

    def _validate(self):
        """Validate authentication info (optional override)"""
        super(MySimpleProvider, self)._validate()
        # Add specific validation logic, like checking API key format
        if not self.token or len(self.token) < 16:
            raise ValueError("Invalid API token format")

    def set_record(self, domain, value, record_type="A", ttl=None, line=None, **extra):
        """Update DNS record - must implement"""
        # logic to update DNS record

BaseProvider Example

Suitable for standard DNS providers, refer to existing implementations:

provider/dnspod.py: POST form data, no signature
provider/cloudflare.py: RESTful JSON, no signature
provider/alidns.py: POST form + sha256 parameter signature
provider/huaweidns.py: RESTful JSON, parameter header signature

provider/myprovider.py

python

# coding=utf-8
"""
Custom standard DNS provider example
@author: YourGithubUsername
"""
from ._base import BaseProvider, TYPE_JSON, hmac_sha256_authorization, sha256_hash

class MyProvider(BaseProvider):
    """
    Example BaseProvider implementation
    Suitable for DNS providers offering complete CRUD APIs
    """
    API = 'https://api.exampledns.com'
    content_type = TYPE_JSON  # or TYPE_FORM

    def _query_zone_id(self, domain):
        # type: (str) -> str | None
        """Query zone ID for main domain"""
        # Exact lookup or list matching

    def _query_record(self, zone_id, subdomain, main_domain, record_type, line=None, extra=None):
        # type: (str, str, str, str, str | None, dict | None) -> Any
        """Query existing DNS record"""

    def _create_record(self, zone_id, subdomain, main_domain, value, record_type, ttl=None, line=None, extra=None):
        # type: (str, str, str, str, str, int | str | None, str | None, dict | None) -> bool
        """Create new DNS record"""

    def _update_record(self, zone_id, old_record, value, record_type, ttl=None, line=None, extra=None):
        # type: (str, dict, str, str, int | str | None, str | None, dict | None) -> bool
        """Update existing DNS record"""

    def _request(self, action, **params):
        # type: (str, **(str | int | bytes | bool | None)) -> dict
        """[Recommended] Encapsulate common request logic, handle auth and common parameters"""
        # Build request parameters
        request_params = {
            "Action": action,
            "Version": "2023-01-01",
            "AccessKeyId": self.id,
            **{k: v for k, v in params.items() if v is not None}
        }

        res = self._http("POST", "/", params=request_params, headers=headers)
        return res.get("data", {})

✅ Development Best Practices

Choosing the Right Base Class

SimpleProvider - For DNS providers with incomplete functionality
- ✅ DNS provider only offers update API
- ✅ No need to query existing records
BaseProvider - Suitable for standard and complex scenarios
- ✅ DNS provider offers complete query, create, modify APIs
- ✅ Need precise record state management
- ✅ Support complex domain resolution logic

General Development Recommendations

🌐 HTTP Request Handling

python

# Use built-in _http method, automatically handles proxy, encoding, logging
response = self._http("POST", path, params=params, headers=headers)

🔒 Format Validation

python

def _validate(self):
    """Authentication info validation example"""
    super(MyProvider, self)._validate()
    # Check API key format
    if not self.token or len(self.token) < 16:
        raise ValueError("API token must be at least 16 characters")

📝 Logging

python

if result:
    self.logger.info("DNS record got: %s", result.get("id"))
    return True
else:
    self.logger.warning("DNS record update returned false")

🧪 Testing and Debugging

Unit Testing

Each Provider should have comprehensive unit tests. The project provides unified test base classes and tools:

python

# tests/test_provider_myprovider.py
from base_test import BaseProviderTestCase, unittest, patch, MagicMock
from ddns.provider.myprovider import MyProvider

class TestMyProvider(BaseProviderTestCase):
    def setUp(self):
        super(TestMyProvider, self).setUp()
        # Provider-specific setup
    
    def test_init_with_basic_config(self):
        """Test basic initialization"""

Running Tests

bash

# Run all tests
python -m unittest discover tests -v

# Run specific Provider tests
python -m unittest tests.test_provider_myprovider -v

# Run specific test method
python tests/test_provider_myprovider.py

📚 More Resources and Best Practices

🏗️ Project Structure Recommendations

text

ddns/
├── provider/
│   ├── _base.py              # Base class definitions
│   ├── myprovider.py         # Your Provider implementation
│   └── __init__.py           # Import and registration
tests/
├── base_test.py              # Shared test base class
├── test_provider_myprovider.py  # Your Provider tests
└── README.md                 # Testing guide

📖 Reference Implementations

SimpleProvider References:

provider/he.py - Hurricane Electric (simple form submission)
provider/debug.py - Debug tool (prints info only)
provider/callback.py - Callback/Webhook mode

BaseProvider References:

provider/cloudflare.py - RESTful JSON API
provider/alidns.py - POST + signature authentication
provider/dnspod.py - POST form data submission

🔐 Cloud Provider Authentication Signature Algorithms

For cloud providers requiring signature authentication (like Alibaba Cloud, Huawei Cloud, Tencent Cloud), DDNS provides generic HMAC-SHA256 signature authentication functions.

Signature Authentication Utility Functions

`hmac_sha256_authorization()` - Generic Signature Generator

Generic cloud provider API authentication signature generation function, supporting Alibaba Cloud, Huawei Cloud, Tencent Cloud and other cloud providers. Uses HMAC-SHA256 algorithm to generate Authorization headers compliant with various cloud provider specifications. All cloud provider differences are passed through template parameters, achieving complete provider independence.

python

from ddns.provider._base import hmac_sha256_authorization, sha256_hash

# Generic signature function call example
authorization = hmac_sha256_authorization(
    secret_key=secret_key,                    # Signature key (already derived)
    method="POST",                            # HTTP method
    path="/v1/domains/records",               # API path
    query="limit=20&offset=0",                # Query string
    headers=request_headers,                  # Request headers dictionary
    body_hash=sha256_hash(request_body),      # Request body hash
    signing_string_format=signing_template,   # Signing string template
    authorization_format=auth_template        # Authorization header template
)

Function Parameters:

Parameter	Type	Description
`secret_key`	`str \| bytes`	Signature key, already processed through key derivation
`method`	`str`	HTTP request method (GET, POST, etc.)
`path`	`str`	API request path
`query`	`str`	URL query string
`headers`	`dict[str, str]`	HTTP request headers
`body_hash`	`str`	SHA256 hash of request body
`signing_string_format`	`str`	Signing string template with `{HashedCanonicalRequest}` placeholder
`authorization_format`	`str`	Authorization header template with `{SignedHeaders}`, `{Signature}` placeholders

Template Variables:

{HashedCanonicalRequest} - SHA256 hash of canonical request
{SignedHeaders} - Alphabetically sorted list of signed headers
{Signature} - Final HMAC-SHA256 signature value

Cloud Provider Signature Implementation Examples

Alibaba Cloud (ACS3-HMAC-SHA256)

python

def _request(self, action, **params):
    # Build request headers
    headers = {
        "host": "alidns.aliyuncs.com",
        "x-acs-action": action,
        "x-acs-content-sha256": sha256_hash(body),
        "x-acs-date": timestamp,
        "x-acs-signature-nonce": nonce,
        "x-acs-version": "2015-01-09"
    }
    
    # Alibaba Cloud signature template
    auth_template = (
        "ACS3-HMAC-SHA256 Credential={access_key},"
        "SignedHeaders={{SignedHeaders}},Signature={{Signature}}"
    )
    signing_template = "ACS3-HMAC-SHA256\n{timestamp}\n{{HashedCanonicalRequest}}"
    
    # Generate signature
    authorization = hmac_sha256_authorization(
        secret_key=self.token,
        method="POST",
        path="/",
        query=query_string,
        headers=headers,
        body_hash=sha256_hash(body),
        signing_string_format=signing_template,
        authorization_format=auth_template
    )
    
    headers["authorization"] = authorization
    return self._http("POST", "/", body=body, headers=headers)

Tencent Cloud (TC3-HMAC-SHA256)

python

def _request(self, action, **params):
    # Tencent Cloud requires derived key
    derived_key = self._derive_signing_key(date, service, self.token)
    
    # Build request headers
    headers = {
        "content-type": "application/json",
        "host": "dnspod.tencentcloudapi.com",
        "x-tc-action": action,
        "x-tc-timestamp": timestamp,
        "x-tc-version": "2021-03-23"
    }
    
    # Tencent Cloud signature template
    auth_template = (
        "TC3-HMAC-SHA256 Credential={secret_id}/{date}/{service}/tc3_request, "
        "SignedHeaders={{SignedHeaders}}, Signature={{Signature}}"
    )
    signing_template = "TC3-HMAC-SHA256\n{timestamp}\n{date}/{service}/tc3_request\n{{HashedCanonicalRequest}}"
    
    # Generate signature
    authorization = hmac_sha256_authorization(
        secret_key=derived_key,  # Note: use derived key
        method="POST",
        path="/",
        query="",
        headers=headers,
        body_hash=sha256_hash(body),
        signing_string_format=signing_template,
        authorization_format=auth_template
    )
    
    headers["authorization"] = authorization
    return self._http("POST", "/", body=body, headers=headers)

Helper Utility Functions

`sha256_hash()` - SHA256 Hash Calculation

python

from ddns.provider._base import sha256_hash

# Calculate SHA256 hash of string
hash_value = sha256_hash("request body content")
# Calculate SHA256 hash of binary data
hash_value = sha256_hash(b"binary data")

`hmac_sha256()` - HMAC-SHA256 Signature Object

python

from ddns.provider._base import hmac_sha256

# Generate HMAC-SHA256 byte signature
# Get HMAC object, can call .digest() for bytes or .hexdigest() for hex string
hmac_obj = hmac_sha256("secret_key", "message_to_sign")
signature_bytes = hmac_obj.digest()        # Byte format
signature_hex = hmac_obj.hexdigest()       # Hex string format

🛠️ Recommended Development Tools

Local development environment: VSCode
Online code editor: GitHub Codespaces or github.dev

🎯 Common Issue Solutions

Q: Why choose SimpleProvider over BaseProvider?
- A: If the DNS provider only offers update API without query API, SimpleProvider is simpler and more efficient

🎉 Summary

Quick Checklist

[ ] Choose appropriate base class (SimpleProvider vs BaseProvider)
[ ] Implement all required methods (with GPT or Copilot assistance)
[ ] Add appropriate error handling and logging
[ ] Write comprehensive unit tests (using GPT or Copilot generation)
[ ] Test various edge cases and error scenarios
[ ] Update relevant documentation

Development Guide: How to Implement a New DNS Provider ​

📦 Directory Structure ​

🚀 Quick Start ​

1. SimpleProvider - Simple DNS Provider ​

2. BaseProvider - Full DNS Provider ⭐️ Recommended ​

🔧 Implementation Examples ​

SimpleProvider Example ​

BaseProvider Example ​

✅ Development Best Practices ​

Choosing the Right Base Class ​

General Development Recommendations ​

🌐 HTTP Request Handling ​

🔒 Format Validation ​

📝 Logging ​

🧪 Testing and Debugging ​

Unit Testing ​

Running Tests ​

📚 More Resources and Best Practices ​

🏗️ Project Structure Recommendations ​

📖 Reference Implementations ​

🔐 Cloud Provider Authentication Signature Algorithms ​

Signature Authentication Utility Functions ​

hmac_sha256_authorization() - Generic Signature Generator ​

Cloud Provider Signature Implementation Examples ​

Alibaba Cloud (ACS3-HMAC-SHA256) ​

Tencent Cloud (TC3-HMAC-SHA256) ​

Helper Utility Functions ​

sha256_hash() - SHA256 Hash Calculation ​

hmac_sha256() - HMAC-SHA256 Signature Object ​

🛠️ Recommended Development Tools ​

🎯 Common Issue Solutions ​

🎉 Summary ​

Quick Checklist ​

Happy Coding! 🚀 ​

Development Guide: How to Implement a New DNS Provider

📦 Directory Structure

🚀 Quick Start

1. SimpleProvider - Simple DNS Provider

2. BaseProvider - Full DNS Provider ⭐️ Recommended

🔧 Implementation Examples

SimpleProvider Example

BaseProvider Example

✅ Development Best Practices

Choosing the Right Base Class

General Development Recommendations

🌐 HTTP Request Handling

🔒 Format Validation

📝 Logging

🧪 Testing and Debugging

Unit Testing

Running Tests

📚 More Resources and Best Practices

🏗️ Project Structure Recommendations

📖 Reference Implementations

🔐 Cloud Provider Authentication Signature Algorithms

Signature Authentication Utility Functions

`hmac_sha256_authorization()` - Generic Signature Generator

Cloud Provider Signature Implementation Examples

Alibaba Cloud (ACS3-HMAC-SHA256)

Tencent Cloud (TC3-HMAC-SHA256)

Helper Utility Functions

`sha256_hash()` - SHA256 Hash Calculation

`hmac_sha256()` - HMAC-SHA256 Signature Object

🛠️ Recommended Development Tools

🎯 Common Issue Solutions

🎉 Summary

Quick Checklist

Happy Coding! 🚀