From 5d022b0520738bb9f993de56892c9257d5428e86 Mon Sep 17 00:00:00 2001
From: Lenard Hess <lenard@rrhess.de>
Date: Mon, 13 Nov 2023 13:15:12 +0100
Subject: [PATCH 1/2] Fixed caching for new providers with legacy 'use'
 parameter

When the configuration used the legacy 'use' parameter, we already
populated the new internal 'wantipv*' field alongside the legacy
'wantip' field. This allows both old and new providers to work.

The legacy providers set 'status'/'ip'.
The new providers then set 'status-ipv*'/'ipv*'.

The caching logic would look for 'status' and 'ip' when encountering a
'use' parameter in the config. We previously already changed ddclient to
set 'status' when 'status-ipv*' was set. Now we also set 'ip' from
'ipv*'. This ensures caching correctly works.
---
 ddclient.in | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/ddclient.in b/ddclient.in
index 1d8a16a..044edee 100755
--- a/ddclient.in
+++ b/ddclient.in
@@ -1345,14 +1345,16 @@ sub update_nics {
             &$update(@hosts);
 
             # Backwards compatibility:
-            # If we only have 'use', we set 'wantipv4' or 'wantipv6' depending on the IP type of
-            # 'wantip'. Newer provider implementations such as cloudflare only check 'wantipv*'
-            # and set 'status-ipv*' accordingly, ignoring 'wantip' and 'status'.
-            # For these we then load back the 'status' from 'status-ipv*' to ensure correct
-            # caching and updating behaviour.
+            # The legacy 'use' parameter sets 'wantip' and the legacy providers process this and
+            # set 'ip', 'status' accordingly.
+            # The new 'usev*' parameters set 'wantipv*' and the new providers set 'ipv*' and 'status-ipv*'.
+            # To allow gradual transition, we make sure both the old 'status' and 'ip' are being set
+            # accordingly to what new providers returned in the new 'status-ipv*' and 'ipv*' fields respectively.
             foreach my $h (@hosts) {
                 $config{$h}{'status'} //= $config{$h}{'status-ipv4'};
                 $config{$h}{'status'} //= $config{$h}{'status-ipv6'};
+                $config{$h}{'ip'} //= $config{$h}{'ipv4'};
+                $config{$h}{'ip'} //= $config{$h}{'ipv6'};
             }
 
             runpostscript(join ' ', keys %ipsv4, keys %ipsv6);

From 30f68e40987a2ed9dc148c9b4000073583013e0a Mon Sep 17 00:00:00 2001
From: Lenard Hess <lenard@rrhess.de>
Date: Thu, 23 Nov 2023 12:50:26 +0100
Subject: [PATCH 2/2] docs: Added initial description on provider
 implementation rules

---
 .github/workflows/scripts/dist-tarball-check |  1 +
 docs/ProviderGuidelines.md                   | 39 ++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/ProviderGuidelines.md

diff --git a/.github/workflows/scripts/dist-tarball-check b/.github/workflows/scripts/dist-tarball-check
index cefb037..36ee6d0 100755
--- a/.github/workflows/scripts/dist-tarball-check
+++ b/.github/workflows/scripts/dist-tarball-check
@@ -34,6 +34,7 @@ try git archive --format=tar --prefix=git-repo/ HEAD \
         .github \
         .gitignore \
         docs/ipv6-design-doc.md \
+        docs/ProviderGuidelines.md \
         shell.nix \
         ;
     # TODO: Delete this next line once support for Automake 1.11 is dropped and
diff --git a/docs/ProviderGuidelines.md b/docs/ProviderGuidelines.md
new file mode 100644
index 0000000..b57b968
--- /dev/null
+++ b/docs/ProviderGuidelines.md
@@ -0,0 +1,39 @@
+# Provider implementations
+
+Author: [@LenardHess](https://github.com/LenardHess/)\
+Date: 2023-11-23
+
+This document is meant to detail the mechanisms that provider implementation shall use. It differentiates between new and legacy provider implementations. The former are adhering to the IPv6 support updates being done to ddclient, the legacy ones are from before that update.
+
+## New provider Implementation
+1. Grab the IP(s) from $config{$host}{'wantipv4'} and/or $config{$host}{'wantipv6'}
+2. Optional: Query the provider for the current IP record(s). If they are already good, skip updating IP record(s)
+3. Update the IP record(s).
+4. If successful (or if the records were already good):
+    - Set 'status-ipv4' and/or 'status-ipv6' to 'good'
+    - Set 'ipv4' and/or 'ipv6' to the IP that has been set
+    - Set 'mtime' to the current time
+5. If not successful:
+    - Set 'status-ipv4' and/or 'status-ipv6' to an error message
+    - Set 'atime' to the current time
+
+The new provider implementation should not set 'status' nor 'ip'. They're part of the legacy infrastructure and ddclient will take care of setting them correctly.
+
+## Legacy provider implementations
+1. Grab the IP from $config{$host}{'wantip'}
+2. Optional: Query the provider for the current IP record. If it is already good, skip updating IP record
+3. Update the IP record.
+4. If successful (or if the record was already good):
+    - Set 'status' to 'good'
+    - Set 'ip' to the IP that has been set
+    - Set 'mtime' to the current time
+5. If not successful:
+    - Set 'status' to an error message
+    - Set 'atime' to the current time
+
+# ToDo
+- Decide/Inquire whether services prefer querying the IP first. Then decide whether to make it mandatory.
+- Write guidelines on checking existing records (i.e. check TTL as well?).
+- Start a list of providers and their implementation state
+- Add more details to this document
+    - Whether 'wantip*' ought to be deleted when read or not.