Merge pull request #595 from ddclient/fix_legacy_caching

.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

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);

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.