From 31229ff627603d5c6e96b5fd4f83792e40fdae89 Mon Sep 17 00:00:00 2001 From: Thilo Schwarz Date: Sat, 31 Oct 2026 12:25:27 +0100 Subject: [PATCH] update README and fix "getRecord" wording in docs and messages - README: fix fluent API examples (getRecord), complete recordCreate docs, document paging, groupRecordsByFqdn, recordDelete by id and multiple types in recordDeleteTypeIfExists, mention Java 17 - replace stray "getRecord" wording with "record" in javadoc, log and exception messages Co-Authored-By: Claude Opus 5.5 --- README.md | 80 +++++++++++++----- changelog.md | 2 + .../java/codes/thischwa/cf/CfDnsClient.java | 82 +++++++++---------- .../java/codes/thischwa/cf/CfRequest.java | 14 ++-- .../thischwa/cf/fluent/RecordOperations.java | 18 ++-- .../cf/fluent/RecordOperationsImpl.java | 2 +- .../thischwa/cf/fluent/package-info.java | 4 +- .../codes/thischwa/cf/model/BatchEntry.java | 4 +- .../thischwa/cf/model/BatchResponse.java | 2 +- .../codes/thischwa/cf/model/RecordEntity.java | 46 +++++------ .../cf/model/RecordMultipleResponse.java | 2 +- .../cf/model/RecordSingleResponse.java | 2 +- .../codes/thischwa/cf/model/RecordType.java | 82 +++++++++---------- .../codes/thischwa/cf/CfClientPenTest.java | 6 +- .../java/codes/thischwa/cf/CfClientTest.java | 18 ++-- 15 files changed, 202 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index 5635142..a919705 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ This guide comes without any warranty. Use at your own risk. The author is not r ## Get It +Java 17 or higher is required. + The project has its own maven repository. Follow the instructions on the latest [package](https://git.mein-gateway.de/thischwa/-/packages/maven/codes.thischwa:cloudflaredns) to add the repository to your project. ## Changelog @@ -33,7 +35,7 @@ See [changelog](changelog.md) The methods can be categorized as follows: - `Zone`: list, info -- `Record`: list, info, create, update, delete +- `Record`: list, info, create, update, delete, batch The API provides two styles for working with DNS records: @@ -71,6 +73,12 @@ List zones = cfDnsClient.zoneList(); zones.forEach(zone -> System.out.println("Zone: " + zone.getName())); ``` +By default, up to 1000 zones are fetched in a single request. Use a `PagingRequest` to control paging: + +```java +List zones = cfDnsClient.zoneList(PagingRequest.of(1, 50)); // page 1, 50 zones per page +``` + --- ### `zoneGet` @@ -129,23 +137,47 @@ List allZoneRecords = cfDnsClient.recordList(zone); // Get only A and AAAA records of a zone List ipZoneRecords = cfDnsClient.recordList(zone, RecordType.A, RecordType.AAAA); + +// Get the records of a zone page by page (page 2, 100 records per page) +List pagedRecords = cfDnsClient.recordList(zone, PagingRequest.of(2, 100)); ``` + +Without a `PagingRequest`, up to 1000 records are fetched in a single request. + +#### Group by FQDN + +The static helper `CfDnsClient.groupRecordsByFqdn` groups a list of records by their fully qualified domain name: + +```java +Map> byFqdn = CfDnsClient.groupRecordsByFqdn(cfDnsClient.recordList(zone)); +``` + --- -### `recordCreate` +### `recordCreateSld` / `recordCreate` Create a new DNS record in a specific zone. - **Parameters**: - - `ZoneEntity zone` - DNS zone object. - - `String sld` - The sub-tld of the new record. - - `int ttl` - The time-to-live in seconds of the new rcord. + - `ZoneEntity zone` - The DNS zone object. + - `String sld` - The second-level domain of the new record (e.g., "api" in "api.example.com"). + - `int ttl` - The time-to-live in seconds of the new record. + - `RecordType type` - The record type (e.g., A, AAAA, CNAME). + - `String content` - The content of the record (e.g., the IP address of an A record). +- **Returns**: The created `RecordEntity`. ```java -RecordEntity created = client.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.1"); +RecordEntity created = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.1"); System.out.println("Created Record ID: " + created.getId()); ``` +Alternatively, the record can be created with its fully qualified name or from a `RecordEntity`: + +```java +cfDnsClient.recordCreate(zone, "api.example.com", 60, RecordType.A, "192.168.1.1"); +cfDnsClient.recordCreate(zone, RecordEntity.build("api.example.com", RecordType.A, 60, "192.168.1.1")); +``` + --- ### `recordUpdate` @@ -177,19 +209,25 @@ boolean isDeleted = cfDnsClient.recordDelete(zone, record); System.out.println(isDeleted ? "Deletion successful." : "Deletion failed."); ``` +If only the ID is known, the record can be deleted by its ID: + +```java +cfDnsClient.recordDelete(zone, record.getId()); +``` + --- ### `recordDeleteTypeIfExists` -Delete a DNS record of a specific type if it exists. +Delete the DNS records of the given types if they exist. - **Parameters**: - `ZoneEntity zone` - Target zone. - `String sld` - Second-level domain. - - `RecordType type` - Record type. + - `RecordType... types` - One or more record types. ```java -cfDnsClient.recordDeleteTypeIfExists(zone, "api", RecordType.A); +cfDnsClient.recordDeleteTypeIfExists(zone, "api", RecordType.A, RecordType.AAAA); System.out.println("Deletion attempt completed."); ``` @@ -320,28 +358,28 @@ that reduces verbosity and improves code readability. ### Basic Usage ```java -// Create a DNS getRecord +// Create a DNS record client.zone("example.com") - .record("api") + .getRecord("api") .create(RecordType.A, "192.168.1.1",60); // Get DNS records of a subdomain List records = client.zone("example.com") - .record("www", RecordType.A) + .getRecord("www", RecordType.A) .get(); // Get all DNS records of a zone List zoneRecords = client.zone("example.com") .list(RecordType.A, RecordType.AAAA); -// Update a DNS getRecord +// Update a DNS record RecordEntity updated = client.zone("example.com") - .record("api", RecordType.A) + .getRecord("api", RecordType.A) .update("192.168.1.2"); // Delete DNS records client.zone("example.com") - .record("old-service") + .getRecord("old-service") .delete(RecordType.A, RecordType.AAAA); ``` @@ -359,25 +397,25 @@ CfDnsClient client = new CfDnsClientBuilder() .withApiTokenAuth("your-api-token") .build(); -// Create a new getRecord +// Create a new record client.zone("example.com") - .record("api") + .getRecord("api") .create(RecordType.A, "192.168.100.1",60); // Retrieve and verify List records = client.zone("example.com") - .record("api", RecordType.A) + .getRecord("api", RecordType.A) .get(); System.out.println("IP: "+records.get(0).getContent()); -// Update the getRecord +// Update the record client.zone("example.com") - .record("api",RecordType.A) + .getRecord("api",RecordType.A) .update("192.168.100.2"); // Clean up client.zone("example.com") - .record("api") + .getRecord("api") .delete(RecordType.A); ``` diff --git a/changelog.md b/changelog.md index 2d97789..7e23c66 100644 --- a/changelog.md +++ b/changelog.md @@ -3,6 +3,8 @@ - 0.6.0-SNAPSHOT: - updated dependencies: jackson 3.2.4, httpclient5 5.6.4, lombok 1.18.48, logback-classic 1.6.6, mockito-junit-jupiter 5.24.0 - updated maven plugins: maven-compiler-plugin 3.16.0, maven-surefire-plugin 3.6.0, maven-jar-plugin 3.5.1 + - README: fixed fluent API examples, documented paging and further methods + - fixed "getRecord" wording in javadoc, log and exception messages (e.g. "Invalid record type") - 0.5.0: - moved the project to git.mein-gateway.de - replaced sonarqube with own actions diff --git a/src/main/java/codes/thischwa/cf/CfDnsClient.java b/src/main/java/codes/thischwa/cf/CfDnsClient.java index f159a62..e852f6a 100644 --- a/src/main/java/codes/thischwa/cf/CfDnsClient.java +++ b/src/main/java/codes/thischwa/cf/CfDnsClient.java @@ -219,11 +219,11 @@ public class CfDnsClient extends CfBasicHttpClient { /** * Retrieves DNS records for the specified second-level domain (SLD) within a zone. - * Optionally, filters by one or more DNS getRecord types. + * Optionally, filters by one or more DNS record types. * * @param zone The zone entity containing information about the domain zone. * @param sld The second-level domain (SLD) for which to retrieve DNS records. - * @param types Optional parameter specifying one or more DNS getRecord types to filter the results. + * @param types Optional parameter specifying one or more DNS record types to filter the results. * @return A list of {@code RecordEntity} objects representing the DNS records for the specified domain. * @throws CloudflareNotFoundException if the specified SLD is not found in the zone * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API @@ -240,10 +240,10 @@ public class CfDnsClient extends CfBasicHttpClient { /** * Retrieves a list of all DNS records for a given zone. - * Optionally, filters by one or more DNS getRecord types. + * Optionally, filters by one or more DNS record types. * * @param zone The zone entity containing information about the domain zone. - * @param types Optional parameter specifying one or more DNS getRecord types to filter the results. + * @param types Optional parameter specifying one or more DNS record types to filter the results. * @return A list of {@code RecordEntity} objects representing the DNS records for the specified zone. * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ @@ -257,17 +257,17 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Creates a new DNS getRecord for a given second-level domain (SLD) within the specified zone. + * Creates a new DNS record for a given second-level domain (SLD) within the specified zone. * - * @param zone The ZoneEntity representing the DNS zone where the getRecord is to be created. - * @param sld The second-level domain (SLD) for which the DNS getRecord is being created. - * @param ttl The time-to-live (TTL) value for the DNS getRecord in seconds. - * @param type The RecordType specifying the type of the DNS getRecord (e.g., A, AAAA, CNAME). - * @param content The content of the DNS getRecord (e.g., IP address for A/AAAA records, target + * @param zone The ZoneEntity representing the DNS zone where the record is to be created. + * @param sld The second-level domain (SLD) for which the DNS record is being created. + * @param ttl The time-to-live (TTL) value for the DNS record in seconds. + * @param type The RecordType specifying the type of the DNS record (e.g., A, AAAA, CNAME). + * @param content The content of the DNS record (e.g., IP address for A/AAAA records, target * domain for CNAME). - * @return The created RecordEntity object containing details of the newly created DNS getRecord. + * @return The created RecordEntity object containing details of the newly created DNS record. * @throws CloudflareApiException If an error occurs while communicating with the Cloudflare API - * or creating the getRecord. + * or creating the record. */ public RecordEntity recordCreateSld(ZoneEntity zone, String sld, int ttl, RecordType type, String content) throws CloudflareApiException { @@ -276,14 +276,14 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Creates a DNS getRecord in the specified DNS zone with the provided details. + * Creates a DNS record in the specified DNS zone with the provided details. * - * @param zone the DNS zone in which the getRecord will be created - * @param name the name of the DNS getRecord (e.g., www.example.com) - * @param ttl the time-to-live (TTL) value for the DNS getRecord - * @param type the type of the DNS getRecord (e.g., A, AAAA, CNAME) - * @param content the content or value of the DNS getRecord - * @return the created DNS getRecord as a {@link RecordEntity} object + * @param zone the DNS zone in which the record will be created + * @param name the name of the DNS record (e.g., www.example.com) + * @param ttl the time-to-live (TTL) value for the DNS record + * @param type the type of the DNS record (e.g., A, AAAA, CNAME) + * @param content the content or value of the DNS record + * @return the created DNS record as a {@link RecordEntity} object * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ public RecordEntity recordCreate(ZoneEntity zone, String name, int ttl, RecordType type, @@ -293,13 +293,13 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Creates a new DNS getRecord in the specified zone using the Cloudflare API. + * Creates a new DNS record in the specified zone using the Cloudflare API. * - * @param zone The zone entity where the getRecord will be created. Contains details such as zone + * @param zone The zone entity where the record will be created. Contains details such as zone * ID. - * @param rec The getRecord entity representing the DNS getRecord to be created, including its + * @param rec The record entity representing the DNS record to be created, including its * attributes. - * @return The created getRecord entity as returned by the Cloudflare API. + * @return The created record entity as returned by the Cloudflare API. * @throws CloudflareApiException If an error occurs while interacting with the Cloudflare API. */ public RecordEntity recordCreate(ZoneEntity zone, RecordEntity rec) @@ -314,11 +314,11 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Deletes a DNS getRecord of the specified type within a given zone on the Cloudflare API. + * Deletes a DNS record of the specified type within a given zone on the Cloudflare API. * - * @param zone The zone entity that specifies the zone in which the getRecord exists. - * @param rec The getRecord entity that represents the DNS getRecord to be deleted. - * @return {@code true} if the DNS getRecord was successfully deleted; {@code false} otherwise. + * @param zone The zone entity that specifies the zone in which the record exists. + * @param rec The record entity that represents the DNS record to be deleted. + * @return {@code true} if the DNS record was successfully deleted; {@code false} otherwise. * @throws CloudflareApiException if there is an issue during the API communication, or the * request fails for any reason. */ @@ -333,11 +333,11 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Deletes a DNS getRecord of the specified type within a given zone on the Cloudflare API. + * Deletes a DNS record of the specified type within a given zone on the Cloudflare API. * - * @param zone The zone entity that specifies the zone in which the getRecord exists. - * @param id The getRecord entity that represents the DNS getRecord to be deleted. - * @return {@code true} if the DNS getRecord was successfully deleted; {@code false} otherwise. + * @param zone The zone entity that specifies the zone in which the record exists. + * @param id The record entity that represents the DNS record to be deleted. + * @return {@code true} if the DNS record was successfully deleted; {@code false} otherwise. * @throws CloudflareApiException if there is an issue during the API communication or the request * fails for any reason. */ @@ -350,12 +350,12 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Updates an existing DNS getRecord in a specified Cloudflare zone. + * Updates an existing DNS record in a specified Cloudflare zone. * * @param zone the zone entity containing the ID of the target zone - * @param rec the getRecord entity containing the ID of the DNS getRecord to be updated and its updated + * @param rec the record entity containing the ID of the DNS record to be updated and its updated * data - * @return the updated getRecord entity as returned by the Cloudflare API + * @return the updated record entity as returned by the Cloudflare API * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ public RecordEntity recordUpdate(ZoneEntity zone, RecordEntity rec) @@ -371,11 +371,11 @@ public class CfDnsClient extends CfBasicHttpClient { } /** - * Deletes DNS records of a specific type within a given zone if they exist. If no getRecord of the + * Deletes DNS records of a specific type within a given zone if they exist. If no record of the * specified type exists, it logs this occurrence without throwing an exception. * - * @param zone The DNS zone entity in which the getRecord exists. - * @param sld The second-level domain for which the getRecord is being checked. + * @param zone The DNS zone entity in which the record exists. + * @param sld The second-level domain for which the record is being checked. * @param recordTypes The types of DNS records that should be deleted if they exist. * @throws CloudflareApiException If an error occurs during API communication. */ @@ -386,7 +386,7 @@ public class CfDnsClient extends CfBasicHttpClient { try { recs = recordList(zone, sld, recordTypes); } catch (CloudflareNotFoundException e) { - log.trace("No getRecord of type {} found for domain {}.", recordTypes, fqdn); + log.trace("No record of type {} found for domain {}.", recordTypes, fqdn); return; } for (RecordEntity rec : recs) { @@ -394,13 +394,13 @@ public class CfDnsClient extends CfBasicHttpClient { recordDelete(zone, rec); log.info("Record {} of type {} successful deleted.", fqdn, recordTypes); } catch (CloudflareApiException e) { - log.error("Failed to delete getRecord {} of type {} for zone {}: {}", fqdn, recordTypes, zone.getName(), e.getMessage()); + log.error("Failed to delete record {} of type {} for zone {}: {}", fqdn, recordTypes, zone.getName(), e.getMessage()); } } } /** - * Processes a batch of DNS getRecord operations (POST, PUT, PATCH, DELETE) for a specified zone. + * Processes a batch of DNS record operations (POST, PUT, PATCH, DELETE) for a specified zone. * This method builds and cleans the input records, sends the batch request to the Cloudflare API, * and returns a result containing processed batch entries. * @@ -416,7 +416,7 @@ public class CfDnsClient extends CfBasicHttpClient { @Nullable List patchRecords, @Nullable List deleteRecords) throws CloudflareApiException { BatchEntry batchEntry = new BatchEntry(); - // build 'clean' getRecord entries + // build 'clean' record entries if (postRecords != null) { batchEntry.setPosts(cleanRecordsForPostOrPut(postRecords)); } diff --git a/src/main/java/codes/thischwa/cf/CfRequest.java b/src/main/java/codes/thischwa/cf/CfRequest.java index c2573de..83f7165 100644 --- a/src/main/java/codes/thischwa/cf/CfRequest.java +++ b/src/main/java/codes/thischwa/cf/CfRequest.java @@ -27,20 +27,20 @@ public enum CfRequest { */ RECORD_LIST("/zones/%s/dns_records"), /** - * Represents the API endpoint path for retrieving information about a DNS getRecord within a + * Represents the API endpoint path for retrieving information about a DNS record within a * specific DNS zone by its name. The endpoint path includes placeholders for the zone identifier - * and the getRecord name, which need to be provided to construct the complete path. + * and the record name, which need to be provided to construct the complete path. */ RECORD_LIST_NAME("/zones/%s/dns_records?name=%s"), /** - * Represents the API endpoint path for creating a new DNS getRecord within a specific DNS zone. The + * Represents the API endpoint path for creating a new DNS record within a specific DNS zone. The * endpoint path includes a placeholder for the zone identifier, which needs to be provided to * construct the complete path. */ RECORD_CREATE("/zones/%s/dns_records"), /** - * Represents the API endpoint path for updating an existing DNS getRecord within a specific DNS - * zone. The endpoint path includes placeholders for the zone identifier and the getRecord + * Represents the API endpoint path for updating an existing DNS record within a specific DNS + * zone. The endpoint path includes placeholders for the zone identifier and the record * identifier, which need to be provided to construct the complete path. */ RECORD_UPDATE("/zones/%s/dns_records/%s"), @@ -51,8 +51,8 @@ public enum CfRequest { */ RECORD_BATCH("/zones/%s/dns_records/batch"), /** - * Represents the API endpoint path for deleting an existing DNS getRecord within a specific DNS - * zone. The endpoint path includes placeholders for the zone identifier and the getRecord + * Represents the API endpoint path for deleting an existing DNS record within a specific DNS + * zone. The endpoint path includes placeholders for the zone identifier and the record * identifier, which need to be provided to construct the complete path. */ RECORD_DELETE("/zones/%s/dns_records/%s"); diff --git a/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java index 281d662..579300b 100644 --- a/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java +++ b/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java @@ -6,7 +6,7 @@ import codes.thischwa.cf.model.RecordType; import java.util.List; /** - * Fluent interface for getRecord-level operations. + * Fluent interface for record-level operations. * Provides a chainable API for CRUD operations on DNS records. */ public interface RecordOperations { @@ -20,29 +20,29 @@ public interface RecordOperations { List get() throws CloudflareApiException; /** - * Creates a new DNS getRecord with the specified parameters. + * Creates a new DNS record with the specified parameters. * - * @param type the DNS getRecord type (e.g., A, AAAA, CNAME) - * @param content the content of the DNS getRecord (e.g., IP address) + * @param type the DNS record type (e.g., A, AAAA, CNAME) + * @param content the content of the DNS record (e.g., IP address) * @param ttl the time-to-live value in seconds * @return the created RecordEntity - * @throws CloudflareApiException if an error occurs while creating the getRecord + * @throws CloudflareApiException if an error occurs while creating the record */ RecordEntity create(RecordType type, String content, int ttl) throws CloudflareApiException; /** - * Updates an existing DNS getRecord with new content. + * Updates an existing DNS record with new content. * - * @param newContent the new content for the DNS getRecord + * @param newContent the new content for the DNS record * @return the updated RecordEntity - * @throws CloudflareApiException if an error occurs while updating the getRecord + * @throws CloudflareApiException if an error occurs while updating the record */ RecordEntity update(String newContent) throws CloudflareApiException; /** * Deletes DNS records of the specified types. * - * @param types the DNS getRecord types to delete + * @param types the DNS record types to delete * @throws CloudflareApiException if an error occurs while deleting records */ void delete(RecordType... types) throws CloudflareApiException; diff --git a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java index eebe8d6..da9a5b7 100644 --- a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java +++ b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java @@ -9,7 +9,7 @@ import java.util.List; import org.jetbrains.annotations.Nullable; /** - * Implementation of RecordOperations for fluent API access to getRecord-level operations. + * Implementation of RecordOperations for fluent API access to record-level operations. */ public class RecordOperationsImpl implements RecordOperations { diff --git a/src/main/java/codes/thischwa/cf/fluent/package-info.java b/src/main/java/codes/thischwa/cf/fluent/package-info.java index 511ec69..dcf8f83 100644 --- a/src/main/java/codes/thischwa/cf/fluent/package-info.java +++ b/src/main/java/codes/thischwa/cf/fluent/package-info.java @@ -6,7 +6,7 @@ * *

Example usage: *


- * // Create a DNS getRecord
+ * // Create a DNS record
  * client.zone("example.com")
  *       .getRecord("api")
  *       .create(RecordType.A, "192.168.1.1", 60);
@@ -16,7 +16,7 @@
  *                                      .getRecord("www", RecordType.A)
  *                                      .get();
  *
- * // Update a DNS getRecord
+ * // Update a DNS record
  * client.zone("example.com")
  *       .getRecord("api", RecordType.A)
  *       .update("192.168.1.2");
diff --git a/src/main/java/codes/thischwa/cf/model/BatchEntry.java b/src/main/java/codes/thischwa/cf/model/BatchEntry.java
index dc93e02..bee8682 100644
--- a/src/main/java/codes/thischwa/cf/model/BatchEntry.java
+++ b/src/main/java/codes/thischwa/cf/model/BatchEntry.java
@@ -5,11 +5,11 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 
 /**
- * Represents a batch entry containing different types of operations on getRecord entities.
+ * Represents a batch entry containing different types of operations on record entities.
  *
  * 

A BatchEntry groups together collections of operations (patches, posts, puts, and deletes) * intended to be performed as part of a single batch process. Each operation corresponds to a specific - * type of action on DNS getRecord entities. + * type of action on DNS record entities. * *

    *
  • patches: A list of {@link RecordEntity} objects representing partial updates to existing records. diff --git a/src/main/java/codes/thischwa/cf/model/BatchResponse.java b/src/main/java/codes/thischwa/cf/model/BatchResponse.java index 9ba4a0c..d66b892 100644 --- a/src/main/java/codes/thischwa/cf/model/BatchResponse.java +++ b/src/main/java/codes/thischwa/cf/model/BatchResponse.java @@ -5,7 +5,7 @@ package codes.thischwa.cf.model; * *

    This class is used for API responses where the primary result is a batch entry, * which includes collections of operations such as patches, posts, puts, and deletes - * performed on DNS getRecord entities. + * performed on DNS record entities. * *

    Extends {@code AbstractSingleResponse} with {@code BatchEntry} as the generic type, * ensuring that the response result is a batch of operations. diff --git a/src/main/java/codes/thischwa/cf/model/RecordEntity.java b/src/main/java/codes/thischwa/cf/model/RecordEntity.java index 5f18daa..7fb32d3 100644 --- a/src/main/java/codes/thischwa/cf/model/RecordEntity.java +++ b/src/main/java/codes/thischwa/cf/model/RecordEntity.java @@ -6,22 +6,22 @@ import lombok.EqualsAndHashCode; import org.jetbrains.annotations.Nullable; /** - * Represents a DNS getRecord entity within a specific zone. + * Represents a DNS record entity within a specific zone. * *

    Attributes defined in this class include: * *

      - *
    • DNS getRecord type such as "A" or "CNAME". - *
    • Name of the DNS getRecord. - *
    • Content of the DNS getRecord, such as an IP address. - *
    • Flags indicating whether the getRecord is proxiable or proxied. - *
    • TTL (Time-To-Live) for the DNS getRecord. - *
    • A locked status to indicate the immutability of the getRecord. + *
    • DNS record type such as "A" or "CNAME". + *
    • Name of the DNS record. + *
    • Content of the DNS record, such as an IP address. + *
    • Flags indicating whether the record is proxiable or proxied. + *
    • TTL (Time-To-Live) for the DNS record. + *
    • A locked status to indicate the immutability of the record. *
    • Zone-specific metadata including zone ID and name. *
    • Timestamps for creation and modification. *
    * - *

    Provides a static factory method {@code build} for creating a DNS getRecord with specific + *

    Provides a static factory method {@code build} for creating a DNS record with specific * attributes. */ @EqualsAndHashCode(callSuper = true) @@ -45,7 +45,7 @@ public class RecordEntity extends AbstractEntity { /** * Initializes a new instance of the RecordEntity class and invokes the parent constructor from - * the AbstractEntity class. The RecordEntity class represents a DNS getRecord entity within a + * the AbstractEntity class. The RecordEntity class represents a DNS record entity within a * specific zone, encapsulating attributes such as type, name, content, TTL, and other related * metadata. */ @@ -56,10 +56,10 @@ public class RecordEntity extends AbstractEntity { /** * Builds and returns a {@link RecordEntity} instance with the specified attributes. * - * @param name the name of the DNS getRecord - * @param type the {@link RecordType} of the DNS getRecord - * @param ttl the time-to-live (TTL) value for the DNS getRecord - * @param content the content of the DNS getRecord, typically an IP address + * @param name the name of the DNS record + * @param type the {@link RecordType} of the DNS record + * @param ttl the time-to-live (TTL) value for the DNS record + * @param content the content of the DNS record, typically an IP address * @return a {@link RecordEntity} populated with the provided attributes */ public static RecordEntity build(String name, RecordType type, Integer ttl, String content) { @@ -74,8 +74,8 @@ public class RecordEntity extends AbstractEntity { /** * Builds and returns a {@link RecordEntity} instance with the specified ID and content. * - * @param id the unique identifier for the DNS getRecord - * @param content the content of the DNS getRecord, typically an IP address or other getRecord data + * @param id the unique identifier for the DNS record + * @param content the content of the DNS record, typically an IP address or other record data * @return a {@link RecordEntity} populated with the provided ID and content */ public static RecordEntity build(String id, String content) { @@ -88,11 +88,11 @@ public class RecordEntity extends AbstractEntity { /** * Builds and returns a {@link RecordEntity} instance with the specified attributes. * - * @param id the unique identifier for the DNS getRecord - * @param name the name of the DNS getRecord - * @param type the type of the DNS getRecord, represented as a string (e.g., "A", "CNAME") - * @param ttl the time-to-live (TTL) value for the DNS getRecord - * @param content the content of the DNS getRecord, typically an IP address or other getRecord data + * @param id the unique identifier for the DNS record + * @param name the name of the DNS record + * @param type the type of the DNS record, represented as a string (e.g., "A", "CNAME") + * @param ttl the time-to-live (TTL) value for the DNS record + * @param content the content of the DNS record, typically an IP address or other record data * @return a {@link RecordEntity} populated with the provided attributes * @throws IllegalArgumentException if the type string is not a valid RecordType */ @@ -101,7 +101,7 @@ public class RecordEntity extends AbstractEntity { try { recordType = RecordType.valueOf(type); } catch (IllegalArgumentException e) { - throw new IllegalArgumentException("Invalid getRecord type: " + type + ". Must be one of: " + throw new IllegalArgumentException("Invalid record type: " + type + ". Must be one of: " + java.util.Arrays.toString(RecordType.values()), e); } RecordEntity rec = new RecordEntity(); @@ -114,11 +114,11 @@ public class RecordEntity extends AbstractEntity { } /** - * Retrieves the short name (subdomain) of the DNS getRecord. + * Retrieves the short name (subdomain) of the DNS record. * If the name contains a dot ('.'), only the substring before the first dot is returned. * This is useful for getting the subdomain part of a fully qualified domain name. * - * @return the short name of the DNS getRecord (substring before the first dot), + * @return the short name of the DNS record (substring before the first dot), * or the full name if no dot is present */ public String getSld() { diff --git a/src/main/java/codes/thischwa/cf/model/RecordMultipleResponse.java b/src/main/java/codes/thischwa/cf/model/RecordMultipleResponse.java index 5ea8672..466e06d 100644 --- a/src/main/java/codes/thischwa/cf/model/RecordMultipleResponse.java +++ b/src/main/java/codes/thischwa/cf/model/RecordMultipleResponse.java @@ -9,7 +9,7 @@ public class RecordMultipleResponse extends AbstractMultipleResponseThis class represents a response containing multiple DNS getRecord entities from the + *

    This class represents a response containing multiple DNS record entities from the * Cloudflare API. It inherits functionality from AbstractMultipleResponse to handle multiple * records of type RecordEntity. */ diff --git a/src/main/java/codes/thischwa/cf/model/RecordSingleResponse.java b/src/main/java/codes/thischwa/cf/model/RecordSingleResponse.java index 48d0a21..5b1b9a0 100644 --- a/src/main/java/codes/thischwa/cf/model/RecordSingleResponse.java +++ b/src/main/java/codes/thischwa/cf/model/RecordSingleResponse.java @@ -11,7 +11,7 @@ public class RecordSingleResponse extends AbstractSingleResponse { * *

    This constructor initializes the RecordSingleResponse object by invoking the superclass * constructor. The RecordSingleResponse represents a specific API response structure that - * encapsulates a single DNS getRecord entity, providing mechanisms to interact with such data in the + * encapsulates a single DNS record entity, providing mechanisms to interact with such data in the * context of the Cloudflare API. */ public RecordSingleResponse() { diff --git a/src/main/java/codes/thischwa/cf/model/RecordType.java b/src/main/java/codes/thischwa/cf/model/RecordType.java index 5d79f53..bff7a80 100644 --- a/src/main/java/codes/thischwa/cf/model/RecordType.java +++ b/src/main/java/codes/thischwa/cf/model/RecordType.java @@ -3,86 +3,86 @@ package codes.thischwa.cf.model; import lombok.Getter; /** - * Enum representing various DNS getRecord types. + * Enum representing various DNS record types. * - *

    Each constant in this enum corresponds to a specific DNS getRecord type, such as "A", "AAAA", - * "CNAME", or "TXT". This enum provides a means to standardize the representation of these getRecord + *

    Each constant in this enum corresponds to a specific DNS record type, such as "A", "AAAA", + * "CNAME", or "TXT". This enum provides a means to standardize the representation of these record * types throughout the application while allowing easy retrieval of their string representation. */ @Getter public enum RecordType { /** - * Represents the DNS A getRecord type. + * Represents the DNS A record type. * - *

    The "A" getRecord type is used to map a domain name to an IPv4 address. + *

    The "A" record type is used to map a domain name to an IPv4 address. */ A("A"), /** - * Represents the DNS AAAA getRecord type. + * Represents the DNS AAAA record type. * - *

    The "AAAA" getRecord type maps a domain name to an IPv6 address. + *

    The "AAAA" record type maps a domain name to an IPv6 address. */ AAAA("AAAA"), /** - * Represents the DNS CAA (Certificate Authority Authorization) getRecord type. + * Represents the DNS CAA (Certificate Authority Authorization) record type. * - *

    The "CAA" getRecord type is used to specify which certificate authorities (CAs) are allowed to + *

    The "CAA" record type is used to specify which certificate authorities (CAs) are allowed to * issue SSL/TLS certificates for a domain. */ CAA("CAA"), /** - * Represents the DNS CERT getRecord type. + * Represents the DNS CERT record type. * - *

    The "CERT" getRecord type is used to store certificates and related certificate revocation + *

    The "CERT" record type is used to store certificates and related certificate revocation * lists or certificate authority data in DNS zones. */ CERT("CERT"), /** - * Represents the DNS CNAME (Canonical Name) getRecord type. + * Represents the DNS CNAME (Canonical Name) record type. * - *

    The "CNAME" getRecord type is used to alias one domain name to another. + *

    The "CNAME" record type is used to alias one domain name to another. */ CNAME("CNAME"), /** - * Represents the DNSKEY getRecord type. + * Represents the DNSKEY record type. * - *

    The "DNSKEY" getRecord type is used for storing public keys in DNS, as part of the DNS Security + *

    The "DNSKEY" record type is used for storing public keys in DNS, as part of the DNS Security * Extensions (DNSSEC). It helps in verifying the authenticity of DNS responses through digital * signatures. */ DNSKEY("DNSKEY"), /** - * Represents the DNS DS (Delegation Signer) getRecord type. + * Represents the DNS DS (Delegation Signer) record type. * - *

    The "DS" getRecord type is used in the DNSSEC (Domain Name System Security Extensions) - * protocol. It contains a hash of a DNSKEY getRecord which is utilized in establishing a chain of + *

    The "DS" record type is used in the DNSSEC (Domain Name System Security Extensions) + * protocol. It contains a hash of a DNSKEY record which is utilized in establishing a chain of * trust from a parent zone to a child zone. */ DS("DS"), /** - * Represents the DNS HTTPS (HTTP Service) getRecord type. + * Represents the DNS HTTPS (HTTP Service) record type. * - *

    The "HTTPS" getRecord type is used to specify information about the HTTP/3 and related services + *

    The "HTTPS" record type is used to specify information about the HTTP/3 and related services * offered by a domain. */ HTTPS("HTTPS"), /** - * Represents the DNS LOC (Location) getRecord type. + * Represents the DNS LOC (Location) record type. * - *

    The "LOC" getRecord type is used to store geographical location information for a domain, + *

    The "LOC" record type is used to store geographical location information for a domain, * including latitude, longitude, altitude, and other details. It enables associating domains with * physical locations. */ LOC("LOC"), /** - * Represents the DNS MX (Mail Exchange) getRecord type. + * Represents the DNS MX (Mail Exchange) record type. * - *

    The "MX" getRecord type is used to specify the mail servers responsible for receiving email + *

    The "MX" record type is used to specify the mail servers responsible for receiving email * messages on behalf of a domain. */ MX("MX"), /** - * Represents the NAPTR getRecord type for DNS configurations. + * Represents the NAPTR record type for DNS configurations. * *

    This constant is used to specify NAPTR (Naming Authority Pointer) DNS records, which allow * for service discovery through flexible DNS-based mechanisms. NAPTR records are commonly used in @@ -99,7 +99,7 @@ public enum RecordType { */ NS("NS"), /** - * Represents the "OPENPGPKEY" DNS getRecord type. + * Represents the "OPENPGPKEY" DNS record type. * *

    This constant is primarily used to identify DNS records of the type "OPENPGPKEY". It may be * utilized within the system for operations such as creating, retrieving, updating, or managing @@ -107,17 +107,17 @@ public enum RecordType { */ OPENPGPKEY("OPENPGPKEY"), /** - * Represents a DNS getRecord type. + * Represents a DNS record type. * - *

    The `PTR` value specifically refers to a "pointer getRecord" in the DNS system, which is + *

    The `PTR` value specifically refers to a "pointer record" in the DNS system, which is * typically used for reverse DNS lookups. */ PTR("PTR"), /** - * Represents the SMIMEA DNS getRecord type. + * Represents the SMIMEA DNS record type. * - *

    The SMIMEA resource getRecord is used to associate a user's certificate information for email - * message signing or encryption. This type of DNS getRecord is part of the DNS-based Authentication + *

    The SMIMEA resource record is used to associate a user's certificate information for email + * message signing or encryption. This type of DNS record is part of the DNS-based Authentication * of Named Entities (DANE) protocol. * *

    SMIMEA records provide a mechanism for utilizing certificates in email communication @@ -134,41 +134,41 @@ public enum RecordType { */ SMIMEA("SMIMEA"), /** - * Represents a service getRecord (SRV) type in the DNS configuration model. + * Represents a service record (SRV) type in the DNS configuration model. * - *

    This constant may be used to identify and work with SRV getRecord types in various DNS-related + *

    This constant may be used to identify and work with SRV record types in various DNS-related * operations or integrations. */ SRV("SRV"), /** - * Represents the DNS getRecord type "SSHFP" (SSH Fingerprint), used in DNS to store cryptographic + * Represents the DNS record type "SSHFP" (SSH Fingerprint), used in DNS to store cryptographic * fingerprints associated with SSH host keys. * - *

    This DNS getRecord type provides a mechanism for verifying the authenticity of an SSH server + *

    This DNS record type provides a mechanism for verifying the authenticity of an SSH server * before initiating a connection, enhancing the security of SSH communications. */ SSHFP("SSHFP"), /** - * Represents the Service Binding (SVCB) DNS getRecord type. + * Represents the Service Binding (SVCB) DNS record type. * - *

    The SVCB getRecord is a DNS resource getRecord used to indicate alternative endpoints or specific + *

    The SVCB record is a DNS resource record used to indicate alternative endpoints or specific * configuration details for services. It is commonly applied in service discovery and * protocol-specific configurations. */ SVCB("SVCB"), /** - * Represents a constant for the DNS-based Authentication of Named Entities (DANE) TLSA getRecord + * Represents a constant for the DNS-based Authentication of Named Entities (DANE) TLSA record * type. * - *

    The TLSA getRecord is used to associate a TLS server certificate or public key with the domain + *

    The TLSA record is used to associate a TLS server certificate or public key with the domain * name (e.g., via DNSSEC). It enables cryptographically secured connections by attaching * certificate and key constraints to the specific domain. */ TLSA("TLSA"), /** - * Represents the TXT DNS getRecord type. + * Represents the TXT DNS record type. * - *

    The TXT DNS getRecord type is commonly used to store text-based information for various + *

    The TXT DNS record type is commonly used to store text-based information for various * verification and configuration purposes, such as domain ownership verification or email * authentication protocols (e.g., SPF, DKIM). */ diff --git a/src/test/java/codes/thischwa/cf/CfClientPenTest.java b/src/test/java/codes/thischwa/cf/CfClientPenTest.java index a2bccb5..82f0186 100644 --- a/src/test/java/codes/thischwa/cf/CfClientPenTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientPenTest.java @@ -66,7 +66,7 @@ public class CfClientPenTest { } @Test - @DisplayName("Invalid getRecord content and TTL boundaries must be rejected by API") + @DisplayName("Invalid record content and TTL boundaries must be rejected by API") void testInvalidRecordCreateInputsRejected() throws Exception { CfDnsClient client = newClient(); ZoneEntity zone = client.zoneGet(ZONE_STR); @@ -81,11 +81,11 @@ public class CfClientPenTest { } try { - // A getRecord with invalid IPv4 + // A record with invalid IPv4 assertThrows(CloudflareApiException.class, () -> client.recordCreate(zone, fqdn, 60, RecordType.A, "999.999.999.999")); - // AAAA getRecord with non-IP content + // AAAA record with non-IP content assertThrows(CloudflareApiException.class, () -> client.recordCreate(zone, fqdn, 60, RecordType.AAAA, "not-an-ipv6")); diff --git a/src/test/java/codes/thischwa/cf/CfClientTest.java b/src/test/java/codes/thischwa/cf/CfClientTest.java index dce178a..882e9f6 100644 --- a/src/test/java/codes/thischwa/cf/CfClientTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientTest.java @@ -144,7 +144,7 @@ public class CfClientTest { // ensure clean state client.recordDeleteTypeIfExists(z, randomSld, RecordType.A, RecordType.AAAA); - // create A getRecord using recordCreate with full domain + // create A record using recordCreate with full domain createdRe1 = client.recordCreate(z, RecordEntity.build(domain, RecordType.A, TTL, "130.0.0.3")); assertNotNull(createdRe1.getId()); @@ -163,7 +163,7 @@ public class CfClientTest { r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); - // create AAAA getRecord using recordCreateSld + // create AAAA record using recordCreateSld createdRe2 = client.recordCreateSld(z, randomSld, TTL, RecordType.AAAA, "2a0a:4cc0:c0:2e4::1"); List aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); @@ -183,7 +183,7 @@ public class CfClientTest { } else if (Objects.equals(re.getType(), RecordType.AAAA.getType())) { assertEquals("2a0a:4cc0:c0:2e4::1", re.getContent()); } else { - fail(String.format("Unexpected getRecord type: %s", re.getType())); + fail(String.format("Unexpected record type: %s", re.getType())); } } @@ -207,7 +207,7 @@ public class CfClientTest { assertFalse(fluentList.isEmpty()); assertTrue(fluentList.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); - // update AAAA getRecord + // update AAAA record createdRe2.setContent("2a0a:4cc0:c0:2e4::2"); client.recordUpdate(z, createdRe2); aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); @@ -215,18 +215,18 @@ public class CfClientTest { r = aaaaRecords.get(0); assertEquals("2a0a:4cc0:c0:2e4::2", r.getContent()); - // verify A getRecord still intact + // verify A record still intact aRecords = client.recordList(z, randomSld, RecordType.A); assertEquals(1, aRecords.size()); r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); - // delete AAAA getRecord and verify it's gone + // delete AAAA record and verify it's gone assertTrue(client.recordDelete(z, createdRe2)); assertThrows(CloudflareNotFoundException.class, () -> client.recordList(z, randomSld, RecordType.AAAA)); - // delete A getRecord using helper and verify it's gone + // delete A record using helper and verify it's gone client.recordDeleteTypeIfExists(z, randomSld, RecordType.A); assertThrows(CloudflareNotFoundException.class, () -> client.recordList(z, randomSld, RecordType.A)); @@ -242,7 +242,7 @@ public class CfClientTest { void testRecordEntityInvalidType() { IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> RecordEntity.build("id123", "example.com", "INVALID_TYPE", 60, "192.168.1.1")); - assertTrue(exception.getMessage().contains("Invalid getRecord type: INVALID_TYPE")); + assertTrue(exception.getMessage().contains("Invalid record type: INVALID_TYPE")); assertTrue(exception.getMessage().contains("Must be one of:")); } @@ -441,7 +441,7 @@ public class CfClientTest { assertNotNull(groupedRecords, "Resulting map should not be null."); assertEquals(2, groupedRecords.size(), "The grouping should result in 2 FQDN keys."); assertEquals(2, groupedRecords.get("example.com.").size(), "The key 'example.com.' should have 2 records."); - assertEquals(1, groupedRecords.get("sub.example.com.").size(), "The key 'sub.example.com.' should have 1 getRecord."); + assertEquals(1, groupedRecords.get("sub.example.com.").size(), "The key 'sub.example.com.' should have 1 record."); } @Test