Feature/email notifications

[Esysc]

Summary

This pull request introduces significant improvements to the DDNS runner script's reliability and updates the project documentation to reflect all current functionality.

The primary fix addresses a critical bug where the run_ddns.sh script failed to correctly capture the Python script's exit code, leading to incorrect notification behavior. The README.md has also been completely overhauled for clarity, accuracy, and completeness, ensuring all features like notifications and exit codes are properly documented.

Key Changes

Bug Fixes

• Correct Exit Code Capture in run_ddns.sh: The script now correctly captures the true exit code from ddns.py. Previously, it would always see an exit code of 0 due to an || true construct, causing notifications to be sent even when the IP was already up-to-date (exit code 7). This is now fixed by temporarily disabling set -e and capturing $? directly after the script execution.

Enhancements & Documentation

• Comprehensive README.md Overhaul: The README.md has been rewritten to be more user-friendly and to serve as a complete reference for the script's features.
  • Added a dedicated section for Email Notifications, explaining all related flags (--smtp, --username, etc.).
  • Clarified the exact conditions under which notifications are sent (i.e., on success/failure, but not when the IP is already up-to-date).
  • Included a new Exit Codes table that documents the meaning of each code returned by ddns.py and its impact on notifications.
  • Streamlined the Quick Start and Usage sections for better clarity.
  • Improved documentation for the token file loading mechanism and pre-commit hooks.
• Added requirements.txt: A formal requirements.txt file has been added. This aligns with the installation logic already present in run_ddns.sh and makes dependency management explicit.

How to Test

1. Verify the Exit Code Fix:

   • Run the script against a record that is already up-to-date:

     # Ensure DDNS_DRY_RUN is not set to 0
     ./run_ddns.sh --zone <your-zone> --name <your-name> --smtp <host> --username <user> --password <pass>

   • Expected behavior: The script should output DDNS script finished with exit code 7 and IP address is already up-to-date. No notification will be sent. No email should be sent.

2. Verify Success Notification:

   • Manually change the IP of your DNS record in the Cloudflare dashboard to something incorrect (e.g., 1.2.3.4).
   • Run the script in live mode:

     DDNS_DRY_RUN=0 ./run_ddns.sh --zone <your-zone> --name <your-name> --smtp <host> --username <user> --password <pass>

   • Expected behavior: The script should output DDNS script finished with exit code 0, and you should receive a "✅ DDNS Update Successful" email.

3. Review the README.md:

   • Read through the new README.md to ensure the instructions are clear, the tables are accurate, and all features are well-documented.

Related Files

• run_ddns.sh
• README.md
• requirements.txt