chore: Merge pull request 'refactor(dns-provider): Rearrange DNS Provider interface' (#229) from docs into master

Reviewed-on: #229
Reviewed-by: Inex Code <inex.code@selfprivacy.org>

lib/logic/providers/dns_providers/cloudflare.dart

@@ -45,21 +45,40 @@ class CloudflareDnsProvider extends DnsProvider {
   }
 
   @override
-  Future<GenericResult<String?>> getZoneId(final String domain) async {
-    String? id;
-    final result = await _adapter.api().getZones(domain);
+  Future<GenericResult<List<String>>> domainList() async {
+    List<String> domains = [];
+    final result = await _adapter.api().getDomains();
     if (result.data.isEmpty || !result.success) {
       return GenericResult(
         success: result.success,
-        data: id,
+        data: domains,
         code: result.code,
         message: result.message,
       );
     }
 
-    id = result.data[0]['id'];
+    domains = result.data
+        .map<String>(
+          (final el) => el['name'] as String,
+        )
+        .toList();
 
-    return GenericResult(success: true, data: id);
+    return GenericResult(
+      success: true,
+      data: domains,
+    );
+  }
+
+  @override
+  Future<GenericResult<void>> createDomainRecords({
+    required final ServerDomain domain,
+    final String? ip4,
+  }) {
+    final records = getProjectDnsRecords(domain.domainName, ip4);
+    return _adapter.api().createMultipleDnsRecords(
+          domain: domain,
+          records: records,
+        );
   }
 
   @override
@@ -116,18 +135,6 @@ class CloudflareDnsProvider extends DnsProvider {
     );
   }
 
-  @override
-  Future<GenericResult<void>> createDomainRecords({
-    required final ServerDomain domain,
-    final String? ip4,
-  }) {
-    final records = getProjectDnsRecords(domain.domainName, ip4);
-    return _adapter.api().createMultipleDnsRecords(
-          domain: domain,
-          records: records,
-        );
-  }
-
   @override
   Future<GenericResult<void>> setDnsRecord(
     final DnsRecord record,
@@ -138,31 +145,6 @@ class CloudflareDnsProvider extends DnsProvider {
         records: [record],
       );
 
-  @override
-  Future<GenericResult<List<String>>> domainList() async {
-    List<String> domains = [];
-    final result = await _adapter.api().getDomains();
-    if (result.data.isEmpty || !result.success) {
-      return GenericResult(
-        success: result.success,
-        data: domains,
-        code: result.code,
-        message: result.message,
-      );
-    }
-
-    domains = result.data
-        .map<String>(
-          (final el) => el['name'] as String,
-        )
-        .toList();
-
-    return GenericResult(
-      success: true,
-      data: domains,
-    );
-  }
-
   @override
   Future<GenericResult<List<DesiredDnsRecord>>> validateDnsRecords(
     final ServerDomain domain,
@@ -353,4 +335,22 @@ class CloudflareDnsProvider extends DnsProvider {
       vpn
     ];
   }
+
+  @override
+  Future<GenericResult<String?>> getZoneId(final String domain) async {
+    String? id;
+    final result = await _adapter.api().getZones(domain);
+    if (result.data.isEmpty || !result.success) {
+      return GenericResult(
+        success: result.success,
+        data: id,
+        code: result.code,
+        message: result.message,
+      );
+    }
+
+    id = result.data[0]['id'];
+
+    return GenericResult(success: true, data: id);
+  }
 }

lib/logic/providers/dns_providers/desec.dart

@@ -45,11 +45,57 @@ class DesecDnsProvider extends DnsProvider {
   }
 
   @override
-  Future<GenericResult<String?>> getZoneId(final String domain) async =>
-      GenericResult(
-        data: domain,
-        success: true,
+  Future<GenericResult<List<String>>> domainList() async {
+    List<String> domains = [];
+    final result = await _adapter.api().getDomains();
+    if (result.data.isEmpty || !result.success) {
+      return GenericResult(
+        success: result.success,
+        data: domains,
+        code: result.code,
+        message: result.message,
       );
+    }
+
+    domains = result.data
+        .map<String>(
+          (final el) => el['name'] as String,
+        )
+        .toList();
+
+    return GenericResult(
+      success: true,
+      data: domains,
+    );
+  }
+
+  @override
+  Future<GenericResult<void>> createDomainRecords({
+    required final ServerDomain domain,
+    final String? ip4,
+  }) async {
+    final List<DnsRecord> listDnsRecords = projectDnsRecords(
+      domain.domainName,
+      ip4,
+    );
+
+    final List<dynamic> bulkRecords = [];
+    for (final DnsRecord record in listDnsRecords) {
+      bulkRecords.add(
+        {
+          'subname': record.name,
+          'type': record.type,
+          'ttl': record.ttl,
+          'records': [extractContent(record)],
+        },
+      );
+    }
+
+    return _adapter.api().createRecords(
+          domain: domain,
+          records: bulkRecords,
+        );
+  }
 
   @override
   Future<GenericResult<void>> removeDomainRecords({
@@ -128,81 +174,6 @@ class DesecDnsProvider extends DnsProvider {
     return GenericResult(success: true, data: records);
   }
 
-  List<DnsRecord> projectDnsRecords(
-    final String? domainName,
-    final String? ip4,
-  ) {
-    final DnsRecord domainA = DnsRecord(type: 'A', name: '', content: ip4);
-
-    final DnsRecord mx =
-        DnsRecord(type: 'MX', name: '', content: '10 $domainName.');
-    final DnsRecord apiA = DnsRecord(type: 'A', name: 'api', content: ip4);
-    final DnsRecord cloudA = DnsRecord(type: 'A', name: 'cloud', content: ip4);
-    final DnsRecord gitA = DnsRecord(type: 'A', name: 'git', content: ip4);
-    final DnsRecord meetA = DnsRecord(type: 'A', name: 'meet', content: ip4);
-    final DnsRecord passwordA =
-        DnsRecord(type: 'A', name: 'password', content: ip4);
-    final DnsRecord socialA =
-        DnsRecord(type: 'A', name: 'social', content: ip4);
-    final DnsRecord vpn = DnsRecord(type: 'A', name: 'vpn', content: ip4);
-
-    final DnsRecord txt1 = DnsRecord(
-      type: 'TXT',
-      name: '_dmarc',
-      content: '"v=DMARC1; p=none"',
-      ttl: 18000,
-    );
-
-    final DnsRecord txt2 = DnsRecord(
-      type: 'TXT',
-      name: '',
-      content: '"v=spf1 a mx ip4:$ip4 -all"',
-      ttl: 18000,
-    );
-
-    return <DnsRecord>[
-      domainA,
-      apiA,
-      cloudA,
-      gitA,
-      meetA,
-      passwordA,
-      socialA,
-      mx,
-      txt1,
-      txt2,
-      vpn
-    ];
-  }
-
-  @override
-  Future<GenericResult<void>> createDomainRecords({
-    required final ServerDomain domain,
-    final String? ip4,
-  }) async {
-    final List<DnsRecord> listDnsRecords = projectDnsRecords(
-      domain.domainName,
-      ip4,
-    );
-
-    final List<dynamic> bulkRecords = [];
-    for (final DnsRecord record in listDnsRecords) {
-      bulkRecords.add(
-        {
-          'subname': record.name,
-          'type': record.type,
-          'ttl': record.ttl,
-          'records': [extractContent(record)],
-        },
-      );
-    }
-
-    return _adapter.api().createRecords(
-          domain: domain,
-          records: bulkRecords,
-        );
-  }
-
   @override
   Future<GenericResult<void>> setDnsRecord(
     final DnsRecord record,
@@ -235,31 +206,6 @@ class DesecDnsProvider extends DnsProvider {
     return content;
   }
 
-  @override
-  Future<GenericResult<List<String>>> domainList() async {
-    List<String> domains = [];
-    final result = await _adapter.api().getDomains();
-    if (result.data.isEmpty || !result.success) {
-      return GenericResult(
-        success: result.success,
-        data: domains,
-        code: result.code,
-        message: result.message,
-      );
-    }
-
-    domains = result.data
-        .map<String>(
-          (final el) => el['name'] as String,
-        )
-        .toList();
-
-    return GenericResult(
-      success: true,
-      data: domains,
-    );
-  }
-
   @override
   Future<GenericResult<List<DesiredDnsRecord>>> validateDnsRecords(
     final ServerDomain domain,
@@ -334,6 +280,53 @@ class DesecDnsProvider extends DnsProvider {
     );
   }
 
+  List<DnsRecord> projectDnsRecords(
+    final String? domainName,
+    final String? ip4,
+  ) {
+    final DnsRecord domainA = DnsRecord(type: 'A', name: '', content: ip4);
+
+    final DnsRecord mx =
+        DnsRecord(type: 'MX', name: '', content: '10 $domainName.');
+    final DnsRecord apiA = DnsRecord(type: 'A', name: 'api', content: ip4);
+    final DnsRecord cloudA = DnsRecord(type: 'A', name: 'cloud', content: ip4);
+    final DnsRecord gitA = DnsRecord(type: 'A', name: 'git', content: ip4);
+    final DnsRecord meetA = DnsRecord(type: 'A', name: 'meet', content: ip4);
+    final DnsRecord passwordA =
+        DnsRecord(type: 'A', name: 'password', content: ip4);
+    final DnsRecord socialA =
+        DnsRecord(type: 'A', name: 'social', content: ip4);
+    final DnsRecord vpn = DnsRecord(type: 'A', name: 'vpn', content: ip4);
+
+    final DnsRecord txt1 = DnsRecord(
+      type: 'TXT',
+      name: '_dmarc',
+      content: '"v=DMARC1; p=none"',
+      ttl: 18000,
+    );
+
+    final DnsRecord txt2 = DnsRecord(
+      type: 'TXT',
+      name: '',
+      content: '"v=spf1 a mx ip4:$ip4 -all"',
+      ttl: 18000,
+    );
+
+    return <DnsRecord>[
+      domainA,
+      apiA,
+      cloudA,
+      gitA,
+      meetA,
+      passwordA,
+      socialA,
+      mx,
+      txt1,
+      txt2,
+      vpn
+    ];
+  }
+
   @override
   List<DesiredDnsRecord> getDesiredDnsRecords(
     final String? domainName,
@@ -415,4 +408,11 @@ class DesecDnsProvider extends DnsProvider {
         ),
     ];
   }
+
+  @override
+  Future<GenericResult<String?>> getZoneId(final String domain) async =>
+      GenericResult(
+        data: domain,
+        success: true,
+      );
 }

lib/logic/providers/dns_providers/digital_ocean_dns.dart

@@ -45,11 +45,42 @@ class DigitalOceanDnsProvider extends DnsProvider {
   }
 
   @override
-  Future<GenericResult<String?>> getZoneId(final String domain) async =>
-      GenericResult(
-        data: domain,
-        success: true,
+  Future<GenericResult<List<String>>> domainList() async {
+    List<String> domains = [];
+    final result = await _adapter.api().domainList();
+    if (result.data.isEmpty || !result.success) {
+      return GenericResult(
+        success: result.success,
+        data: domains,
+        code: result.code,
+        message: result.message,
       );
+    }
+
+    domains = result.data
+        .map<String>(
+          (final el) => el['name'] as String,
+        )
+        .toList();
+
+    return GenericResult(
+      success: true,
+      data: domains,
+    );
+  }
+
+  @override
+  Future<GenericResult<void>> createDomainRecords({
+    required final ServerDomain domain,
+    final String? ip4,
+  }) async =>
+      _adapter.api().createMultipleDnsRecords(
+            domain: domain,
+            records: getProjectDnsRecords(
+              domain.domainName,
+              ip4,
+            ),
+          );
 
   @override
   Future<GenericResult<void>> removeDomainRecords({
@@ -111,19 +142,6 @@ class DigitalOceanDnsProvider extends DnsProvider {
     return GenericResult(data: records, success: true);
   }
 
-  @override
-  Future<GenericResult<void>> createDomainRecords({
-    required final ServerDomain domain,
-    final String? ip4,
-  }) async =>
-      _adapter.api().createMultipleDnsRecords(
-            domain: domain,
-            records: getProjectDnsRecords(
-              domain.domainName,
-              ip4,
-            ),
-          );
-
   @override
   Future<GenericResult<void>> setDnsRecord(
     final DnsRecord record,
@@ -134,31 +152,6 @@ class DigitalOceanDnsProvider extends DnsProvider {
         records: [record],
       );
 
-  @override
-  Future<GenericResult<List<String>>> domainList() async {
-    List<String> domains = [];
-    final result = await _adapter.api().domainList();
-    if (result.data.isEmpty || !result.success) {
-      return GenericResult(
-        success: result.success,
-        data: domains,
-        code: result.code,
-        message: result.message,
-      );
-    }
-
-    domains = result.data
-        .map<String>(
-          (final el) => el['name'] as String,
-        )
-        .toList();
-
-    return GenericResult(
-      success: true,
-      data: domains,
-    );
-  }
-
   @override
   Future<GenericResult<List<DesiredDnsRecord>>> validateDnsRecords(
     final ServerDomain domain,
@@ -356,4 +349,11 @@ class DigitalOceanDnsProvider extends DnsProvider {
         ),
     ];
   }
+
+  @override
+  Future<GenericResult<String?>> getZoneId(final String domain) async =>
+      GenericResult(
+        data: domain,
+        success: true,
+      );
 }

lib/logic/providers/dns_providers/dns_provider.dart

@@ -16,31 +16,69 @@ abstract class DnsProvider {
   ///
   /// If success, saves it for future usage.
   Future<GenericResult<bool>> tryInitApiByToken(final String token);
-  Future<GenericResult<String?>> getZoneId(final String domain);
-  Future<GenericResult<void>> removeDomainRecords({
-    required final ServerDomain domain,
-    final String? ip4,
-  });
-  Future<GenericResult<List<DnsRecord>>> getDnsRecords({
-    required final ServerDomain domain,
-  });
+
+  /// Returns list of all available domain entries assigned to the account.
+  Future<GenericResult<List<String>>> domainList();
+
+  /// Tries to create all main domain records needed
+  /// for SelfPrivacy to launch on requested domain by ip4.
+  ///
+  /// Doesn't check for duplication, cleaning has
+  /// to be done beforehand by [removeDomainRecords]
   Future<GenericResult<void>> createDomainRecords({
     required final ServerDomain domain,
     final String? ip4,
   });
+
+  /// Tries to remove all domain records of requested domain by ip4.
+  ///
+  /// Will remove all entries, including the ones
+  /// that weren't created by SelfPrivacy.
+  Future<GenericResult<void>> removeDomainRecords({
+    required final ServerDomain domain,
+    final String? ip4,
+  });
+
+  /// Returns list of all [DnsRecord] entries assigned to requested domain.
+  Future<GenericResult<List<DnsRecord>>> getDnsRecords({
+    required final ServerDomain domain,
+  });
+
+  /// Tries to create or update a domain record needed
+  /// on requested domain.
+  ///
+  /// Doesn't check for duplication, cleaning has
+  /// to be done beforehand by [removeDomainRecords]
   Future<GenericResult<void>> setDnsRecord(
     final DnsRecord record,
     final ServerDomain domain,
   );
-  Future<GenericResult<List<String>>> domainList();
+
+  /// Tries to check whether all known DNS records on the domain by ip4
+  /// match expectations of SelfPrivacy in order to launch.
+  ///
+  /// Will return list of [DesiredDnsRecord] objects, which represent
+  /// only those records which have successfully passed validation.
   Future<GenericResult<List<DesiredDnsRecord>>> validateDnsRecords(
     final ServerDomain domain,
     final String ip4,
     final String dkimPublicKey,
   );
+
+  /// Will return list of [DesiredDnsRecord] objects, which represent
+  /// samples of perfect DNS records we need to know about in order to launch
+  /// SelfPrivacy application correctly.
   List<DesiredDnsRecord> getDesiredDnsRecords(
     final String? domainName,
     final String? ip4,
     final String? dkimPublicKey,
   );
+
+  /// Tries to access zone of requested domain.
+  ///
+  /// If a DNS provider doesn't support zones,
+  /// will return domain without any changes.
+  ///
+  /// If success, returns an initializing string of zone id.
+  Future<GenericResult<String?>> getZoneId(final String domain);
 }