diff --git a/README.md b/README.md index a919705..38e61b2 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,15 @@ CfDnsClient cfDnsClient = new CfDnsClientBuilder() .build(); ``` +The client is thread-safe and should be reused, it holds a pool of HTTP connections. +`CfDnsClient` implements `AutoCloseable`, call `close()` (or use try-with-resources) to release the connections: + +```java +try (CfDnsClient cfDnsClient = new CfDnsClientBuilder().withApiTokenAuth("your-api-token").build()) { + // ... +} +``` + ### `zoneList` Retrieve all zones within the Cloudflare account. @@ -100,49 +109,53 @@ System.out.println("Zone ID: " + zone.getId()); Retrieve records for a given zone. There are two variants: -#### List by SLD -Retrieve all records for a specific second-level domain (SLD) under a given zone. +#### List by subdomain (`recordListBySubdomain`) +Retrieve all records for a specific subdomain under a given zone, optionally filtered by record types. - **Parameters**: - `ZoneEntity zone` - The zone object. - - `String sld` - Second-level domain (e.g., "www" in "www.example.com"). + - `String subdomain` - The subdomain relative to the zone (e.g., "www" in "www.example.com" + or "my.sub" in "my.sub.example.com"). Use `CfDnsClient.APEX` (`"@"`) for the zone apex. + - `RecordType... types` - Optional record types to filter by. If not specified, returns all record types. - **Returns**: A list of `RecordEntity` objects. ```java -List records = cfDnsClient.recordList(zone, "sld"); -records.forEach(record -> - System.out.println("Record Type: "+record.getType() - +", Value: "+record.getContent()) -); +// Get all records for a specific subdomain +List wwwRecords = cfDnsClient.recordListBySubdomain(zone, "www"); + +// Get only A records for a specific subdomain +List wwwARecords = cfDnsClient.recordListBySubdomain(zone, "www", RecordType.A); + +// Get the records of the zone apex (e.g. "example.com") +List apexRecords = cfDnsClient.recordListBySubdomain(zone, CfDnsClient.APEX); ``` -#### List by Zone (optional filtering) -Retrieve DNS record details for a zone or a specific SLD, optionally filtered by record types. - -- **Parameters**: - - `ZoneEntity zone` - The zone object. - - `String sld` - (Optional) The second-level domain. - - `RecordType... types` - Optional record types to filter by (e.g., A, CNAME). If not specified, returns all record types. -- **Returns**: A list of `RecordEntity` objects matching the criteria. +#### List by type (`recordListByType`) +Retrieve all records of a zone, optionally filtered by record types. ```java -// Get all records for a specific SLD -List allSldRecords = cfDnsClient.recordList(zone, "www"); +// Get only A and AAAA records of a zone +List ipZoneRecords = cfDnsClient.recordListByType(zone, RecordType.A, RecordType.AAAA); +``` -// Get only A records for a specific SLD -List aSldRecords = cfDnsClient.recordList(zone, "www", RecordType.A); +If exactly one record type is given, the filtering is done by Cloudflare, otherwise by the client. +#### List all records of a zone (`recordList`) + +```java // Get all records of a zone 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. +Without a `PagingRequest`, all pages are fetched and the complete result is returned. +With a `PagingRequest`, exactly the requested page is returned. + +`RecordEntity#getSubdomain()` returns the record name relative to its zone, e.g. `my.sub` for +`my.sub.example.com` and `"@"` for the zone apex. The timestamps `getCreatedOn()` and `getModifiedOn()` +are of type `java.time.Instant` (UTC). #### Group by FQDN @@ -154,20 +167,20 @@ Map> byFqdn = CfDnsClient.groupRecordsByFqdn(cfDnsCli --- -### `recordCreateSld` / `recordCreate` +### `recordCreateSubdomain` / `recordCreate` Create a new DNS record in a specific zone. - **Parameters**: - `ZoneEntity zone` - The DNS zone object. - - `String sld` - The second-level domain of the new record (e.g., "api" in "api.example.com"). + - `String subdomain` - The subdomain of the new record relative to the zone (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 = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.1"); +RecordEntity created = cfDnsClient.recordCreateSubdomain(zone, "api", 60, RecordType.A, "192.168.1.1"); System.out.println("Created Record ID: " + created.getId()); ``` @@ -178,11 +191,28 @@ 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")); ``` +Records which need more than a content, like MX, SRV or CAA records, can be created from a `RecordEntity`. +Besides `priority` and `data`, the attributes `proxied`, `comment` and `tags` are supported: + +```java +// MX record with priority +RecordEntity mx = RecordEntity.build("example.com", RecordType.MX, 3600, "mail.example.com"); +mx.setPriority(10); +cfDnsClient.recordCreate(zone, mx); + +// SRV record with structured data (keys as in the Cloudflare API) +RecordEntity srv = RecordEntity.build("_sip._tcp.example.com", RecordType.SRV, 3600, null); +srv.setPriority(10); +srv.setData(Map.of("weight", 5, "port", 5060, "target", "sip.example.com")); +cfDnsClient.recordCreate(zone, srv); +``` + --- ### `recordUpdate` -Update an existing DNS record. +Update an existing DNS record (partial update: attributes which are `null` remain unchanged). +Read-only attributes like timestamps are ignored, the given `RecordEntity` isn't modified. - **Parameters**: - `ZoneEntity zone` - The zone that contains the record. @@ -223,7 +253,7 @@ Delete the DNS records of the given types if they exist. - **Parameters**: - `ZoneEntity zone` - Target zone. - - `String sld` - Second-level domain. + - `String subdomain` - The subdomain relative to the zone. - `RecordType... types` - One or more record types. ```java @@ -266,8 +296,8 @@ Partially update existing records. **Record IDs are required** - fetch them firs ```java // Step 1: Fetch existing records to get their IDs List recordsToUpdate = new ArrayList<>(); -recordsToUpdate.add(cfDnsClient.recordList(zone, "api",RecordType.A).get(0)); -recordsToUpdate.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); +recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "api",RecordType.A).get(0)); +recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0)); // Step 2: Modify only the fields you want to update recordsToUpdate.forEach(record ->record.setContent("192.168.2.10")); @@ -284,8 +314,8 @@ Fully replace existing records. **Record IDs are required** - fetch them first: ```java // Step 1: Fetch existing records to get their IDs List recordsToReplace = new ArrayList<>(); -recordsToReplace.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0)); -recordsToReplace.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); +recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0)); +recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0)); // Step 2: Modify all fields as needed (full replacement) recordsToReplace.get(0).setContent("192.168.3.10"); @@ -305,8 +335,8 @@ Delete existing records. **Record IDs are required** - fetch them first: ```java // Step 1: Fetch existing records to get their IDs List recordsToDelete = new ArrayList<>(); -recordsToDelete.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0)); -recordsToDelete.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0)); +recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0)); +recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0)); // Step 2: Send batch delete request BatchEntry result = cfDnsClient.recordBatch(zone, null, null, null, recordsToDelete); @@ -325,12 +355,12 @@ List newRecords = Arrays.asList( // Fetch existing records for update/delete (IDs required) List recordsToUpdate = Arrays.asList( - cfDnsClient.recordList(zone, "existing-api", RecordType.A).get(0) + cfDnsClient.recordListBySubdomain(zone, "existing-api", RecordType.A).get(0) ); recordsToUpdate.get(0).setContent("192.168.1.200"); List recordsToDelete = Arrays.asList( - cfDnsClient.recordList(zone, "old-api", RecordType.A).get(0) + cfDnsClient.recordListBySubdomain(zone, "old-api", RecordType.A).get(0) ); // Execute all operations in a single batch request @@ -425,7 +455,10 @@ client.zone("example.com") The `CfDnsClient` provides internal error-handling mechanisms through exceptions. For example: - `CloudflareApiException` is thrown for errors during API communication or invalid responses. -- `CloudflareNotFoundException` is thrown when the requested resource (single or multiple) is not found, if enabled via the `emptyResultThrowsException` flag during initialization. **Default is `false`**, meaning empty results will be returned without throwing an exception. + `getStatusCode()` returns the HTTP status code (or `CloudflareApiException.NO_STATUS_CODE` if there was no response) + and `getErrors()` the error codes and messages reported by Cloudflare. +- `CloudflareNotFoundException` is thrown if Cloudflare responds with HTTP status 404 (e.g. deleting a non-existing record). +- `CloudflareNotFoundException` is also thrown when the requested resource (single or multiple) is not found, if enabled via the `emptyResultThrowsException` flag during initialization. **Default is `false`**, meaning empty results will be returned without throwing an exception. To enable exception throwing for empty results: @@ -440,13 +473,14 @@ CfDnsClient client = new CfDnsClientBuilder() ```java try { - List records = cfDnsClient.recordList(zone, "www", RecordType.A); + List records = cfDnsClient.recordListBySubdomain(zone, "www", RecordType.A); System.out.println("Record IP: "+records.get(0).getContent()); } catch (CloudflareApiException e) { if (e instanceof CloudflareNotFoundException) { - log.warn("Sld not found: www"); + log.warn("Subdomain not found: www"); } else { - log.error("Error while getting sld info of www", e); + log.error("Error while getting records of subdomain www (HTTP status {}, errors {})", + e.getStatusCode(), e.getErrors(), e); throw e; } } diff --git a/changelog.md b/changelog.md index 7e23c66..eec59bb 100644 --- a/changelog.md +++ b/changelog.md @@ -1,10 +1,34 @@ # Changelog - 0.6.0-SNAPSHOT: + - **Breaking Changes**: + - `recordList` overloads replaced, because they were ambiguous (e.g. `recordList(zone, null)` didn't compile): + - `recordList(zone, String subdomain, RecordType... types)` and `recordList(zone, String subdomain)` → `recordListBySubdomain(zone, subdomain, types...)` + - `recordList(zone, RecordType... types)` → `recordListByType(zone, types...)` + - `recordList(zone)` and `recordList(zone, PagingRequest)` remain unchanged + - timestamps of `RecordEntity` and `ZoneEntity` (`createdOn`, `modifiedOn`, `activatedOn`) are of type `java.time.Instant` instead of `LocalDateTime`, so the time zone (UTC) isn't lost anymore + - Cloudflare responses with HTTP status 404 throw a `CloudflareNotFoundException` (independent of `emptyResultThrowsException`) + - unexpected runtime exceptions aren't wrapped into a `CloudflareApiException("Unexpected error!")` anymore + - batch DELETE sends only the record IDs, batch PATCH sends all writable attributes which aren't `null` (before: only the content) + - `CfDnsClient` uses one shared HTTP client with connection pooling instead of a new one per request and implements `AutoCloseable`, call `close()` to release the connections + - `CloudflareApiException` provides the HTTP status code (`getStatusCode()`) and the errors reported by Cloudflare (`getErrors()`) + - `RecordEntity` supports the attributes `priority` (MX, SRV, URI), `data` (e.g. SRV, CAA), `comment` and `tags`; they are also considered by batch operations, as is `proxied` + - `recordCreate` and `recordUpdate` don't modify the given `RecordEntity` anymore and send only writable attributes + - fluent `update(content)` sends only the new content (partial update) + - filtering by exactly one record type is done by Cloudflare (`?type=`), unknown record types in responses don't break the client-side filter anymore - 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") + - **Deprecation**: the misleading term "sld" was renamed to "subdomain", the old methods will be removed in a future release: + - `RecordEntity#getSld()` → `RecordEntity#getSubdomain()` + - `CfDnsClient#recordCreateSld(...)` → `CfDnsClient#recordCreateSubdomain(...)` + - `getSubdomain()` returns `"@"` for the zone apex; `CfDnsClient.APEX` can be used to address the zone apex + - fixed: API errors were wrapped into a generic "Unexpected error!" exception + - fixed: `zoneGet` threw an `IndexOutOfBoundsException` for unknown zones, it now returns `null` or throws a `CloudflareNotFoundException` (depending on `emptyResultThrowsException`) + - fixed: `getSubdomain()` failed for apex records and records with multi-level subdomains, batch operations now send the full record name + - fixed: `zoneList()` and `recordList(...)` without `PagingRequest` returned only the first page, now all pages are fetched + - fixed: `recordDelete` threw a `NullPointerException` for an empty result - 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/CfBasicHttpClient.java b/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java index d1b4edb..e50a80b 100644 --- a/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java +++ b/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java @@ -1,7 +1,11 @@ package codes.thischwa.cf; import codes.thischwa.cf.model.AbstractResponse; +import codes.thischwa.cf.model.ResponseResultInfo; +import java.io.IOException; import java.nio.charset.StandardCharsets; +import java.util.List; +import java.util.stream.Collectors; import lombok.extern.slf4j.Slf4j; import org.apache.hc.client5.http.classic.methods.HttpDelete; import org.apache.hc.client5.http.classic.methods.HttpGet; @@ -14,6 +18,7 @@ import org.apache.hc.core5.http.ClassicHttpRequest; import org.apache.hc.core5.http.ClassicHttpResponse; import org.apache.hc.core5.http.ContentType; import org.apache.hc.core5.http.HttpHeaders; +import org.apache.hc.core5.http.HttpStatus; import org.apache.hc.core5.http.io.entity.EntityUtils; import org.apache.hc.core5.http.io.entity.StringEntity; import org.apache.hc.core5.http.message.BasicClassicHttpRequest; @@ -25,13 +30,17 @@ import tools.jackson.databind.ObjectMapper; * Abstract base class for creating HTTP clients to interact with the Cloudflare API. Provides * methods for handling GET and POST requests and includes utilities for constructing HTTP clients, * managing authentication, and handling JSON serialization. + * + *

One underlying HTTP client (with connection pooling) is shared for all requests. It is + * released by {@link #close()}. */ @Slf4j -abstract class CfBasicHttpClient { +abstract class CfBasicHttpClient implements AutoCloseable { private final String baseUrl; private final CfDnsClientBuilder.CfAuth auth; private final ObjectMapper objectMapper; + private final CloseableHttpClient httpClient; private record ResultWrapper(int statusCode, String responseBody) { } @@ -46,6 +55,18 @@ abstract class CfBasicHttpClient { this.baseUrl = baseUrl; this.auth = auth; this.objectMapper = JsonConf.initObjectMapper(); + this.httpClient = createHttpClient(); + } + + /** + * Releases the underlying HTTP client and its connections. The client must not be used anymore + * afterwards. + * + * @throws IOException if an I/O error occurs while closing the HTTP client + */ + @Override + public void close() throws IOException { + httpClient.close(); } private CloseableHttpClient createHttpClient() { @@ -63,45 +84,50 @@ abstract class CfBasicHttpClient { private T executeRequest(ClassicHttpRequest request, Class responseType) throws CloudflareApiException { - String logUri = null; - try (CloseableHttpClient client = createHttpClient()) { - ResultWrapper result = client.execute(request, - (ClassicHttpResponse response) -> new ResultWrapper(response.getCode(), - EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8))); - - - T respObj = objectMapper.readValue(result.responseBody, responseType); - if (!respObj.getResponseResultInfo().isSuccess()) { - log.error("API error."); - StringBuilder errorMessage = new StringBuilder("API error"); - if (!respObj.getResponseResultInfo().getErrors().isEmpty()) { - errorMessage.append(": "); - respObj.getResponseResultInfo().getErrors().forEach(e -> { - log.error(" - {}", e.toString()); - errorMessage.append(e).append("; "); - }); - // Remove trailing "; " - if (errorMessage.toString().endsWith("; ")) { - errorMessage.setLength(errorMessage.length() - 2); - } - } - throw new CloudflareApiException(errorMessage.toString()); - } - logUri = request.getRequestUri(); - if (result.statusCode >= 200 && result.statusCode < 300) { - return respObj; - } else { - log.error("{} request failed for URL {}: Status {}", request.getMethod(), request.getUri(), - result.statusCode); - throw new CloudflareApiException( - request.getMethod() + " request failed with status code: " + result.statusCode); - } - } catch (JacksonException e) { - log.error("JSON parsing error for request to {}", logUri, e); - throw new CloudflareApiException("Error processing JSON response", e); - } catch (Exception e) { - throw new CloudflareApiException("Unexpected error!", e); + String requestInfo = request.getMethod() + " " + request.getRequestUri(); + ResultWrapper result; + try { + result = httpClient.execute(request, (ClassicHttpResponse response) -> new ResultWrapper( + response.getCode(), + response.getEntity() == null ? "" + : EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8))); + } catch (IOException e) { + throw new CloudflareApiException("Request failed: " + requestInfo, e); } + + boolean httpSuccess = result.statusCode >= 200 && result.statusCode < 300; + T respObj; + try { + respObj = objectMapper.readValue(result.responseBody, responseType); + } catch (JacksonException e) { + if (!httpSuccess) { + // e.g. an HTML error page of a proxy + throw buildException(requestInfo + " failed with status code " + result.statusCode, + result.statusCode, null); + } + throw new CloudflareApiException("Error processing JSON response of " + requestInfo, e); + } + + ResponseResultInfo resultInfo = respObj.getResponseResultInfo(); + boolean apiSuccess = resultInfo != null && resultInfo.isSuccess(); + if (!httpSuccess || !apiSuccess) { + List errors = resultInfo == null ? null : resultInfo.getErrors(); + String message = "API error"; + if (errors != null && !errors.isEmpty()) { + message += ": " + errors.stream().map(Object::toString).collect(Collectors.joining("; ")); + } + log.debug("{} failed with status code {}: {}", requestInfo, result.statusCode, message); + throw buildException(message, result.statusCode, errors); + } + return respObj; + } + + private static CloudflareApiException buildException(String message, int statusCode, + List errors) { + if (statusCode == HttpStatus.SC_NOT_FOUND) { + return new CloudflareNotFoundException(message, statusCode, errors); + } + return new CloudflareApiException(message, statusCode, errors); } /** diff --git a/src/main/java/codes/thischwa/cf/CfDnsClient.java b/src/main/java/codes/thischwa/cf/CfDnsClient.java index e852f6a..e428435 100644 --- a/src/main/java/codes/thischwa/cf/CfDnsClient.java +++ b/src/main/java/codes/thischwa/cf/CfDnsClient.java @@ -2,6 +2,7 @@ package codes.thischwa.cf; import codes.thischwa.cf.fluent.ZoneOperations; import codes.thischwa.cf.fluent.ZoneOperationsImpl; +import codes.thischwa.cf.model.AbstractMultipleResponse; import codes.thischwa.cf.model.AbstractResponse; import codes.thischwa.cf.model.BatchEntry; import codes.thischwa.cf.model.BatchResponse; @@ -10,14 +11,17 @@ import codes.thischwa.cf.model.RecordEntity; import codes.thischwa.cf.model.RecordMultipleResponse; import codes.thischwa.cf.model.RecordSingleResponse; import codes.thischwa.cf.model.RecordType; +import codes.thischwa.cf.model.ResponseEntity; +import codes.thischwa.cf.model.ResultInfo; import codes.thischwa.cf.model.ZoneEntity; import codes.thischwa.cf.model.ZoneMultipleResponse; import java.util.ArrayList; import java.util.Arrays; import java.util.HashMap; -import java.util.HashSet; +import java.util.LinkedHashMap; import java.util.List; import java.util.Map; +import java.util.Objects; import java.util.Set; import java.util.stream.Collectors; import lombok.extern.slf4j.Slf4j; @@ -28,26 +32,30 @@ import org.jetbrains.annotations.Nullable; * records and zones within the Cloudflare system, including creating, updating, retrieving, and * deleting DNS records. * + *

The client is thread-safe and should be reused. It holds a pool of HTTP connections, which is + * released by {@link #close()}. + * *

Example with API token authentication (recommended): *


  * // Create a new CfDnsClient instance with API token
- * CfDnsClient cfDnsClient = new CfDnsClientBuilder()
+ * try (CfDnsClient cfDnsClient = new CfDnsClientBuilder()
  *     .withApiTokenAuth("your-api-token")
- *     .build();
+ *     .build()) {
  *
- * // Retrieve a zone
- * ZoneEntity zone = cfDnsClient.zoneGet("example.com");
- * System.out.println("Zone ID: " + zone.getId());
+ *   // Retrieve a zone
+ *   ZoneEntity zone = cfDnsClient.zoneGet("example.com");
+ *   System.out.println("Zone ID: " + zone.getId());
  *
- * // Retrieve records of a subdomain
- * List<RecordEntity> records = cfDnsClient.recordList(zone, "sld");
- * records.forEach(record ->
- *     System.out.println("Record Type: " + record.getType() + ", Value: " + record.getContent())
- * );
+ *   // Retrieve records of a subdomain
+ *   List<RecordEntity> records = cfDnsClient.recordListBySubdomain(zone, "www");
+ *   records.forEach(record ->
+ *       System.out.println("Record Type: " + record.getType() + ", Value: " + record.getContent())
+ *   );
  *
- * // Create a record for the subdomain "api"
- * RecordEntity created = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.10");
- * System.out.println("Created Record ID: " + created.getId());
+ *   // Create a record for the subdomain "api"
+ *   RecordEntity created = cfDnsClient.recordCreateSubdomain(zone, "api", 60, RecordType.A, "192.168.1.10");
+ *   System.out.println("Created Record ID: " + created.getId());
+ * }
  * 
* *

Example with email/key authentication (legacy): @@ -77,6 +85,21 @@ import org.jetbrains.annotations.Nullable; @Slf4j public class CfDnsClient extends CfBasicHttpClient { + /** + * Page size used when fetching all zones. Cloudflare allows max. 50 zones per page. + */ + static final int ZONES_PER_PAGE = 50; + + /** + * Page size used when fetching all DNS records. + */ + static final int RECORDS_PER_PAGE = 1000; + + /** + * Conventional name for the zone apex (the zone name itself). + */ + public static final String APEX = "@"; + private final ResponseValidator responseValidator; private final boolean emptyResultThrowsException; @@ -96,8 +119,11 @@ public class CfDnsClient extends CfBasicHttpClient { this.emptyResultThrowsException = emptyResultThrowsException; } - private static String buildFqdn(ZoneEntity zone, String sld) { - return sld + "." + zone.getName(); + private static String buildFqdn(ZoneEntity zone, String subdomain) { + if (APEX.equals(subdomain)) { + return zone.getName(); + } + return subdomain + "." + zone.getName(); } /** @@ -129,25 +155,30 @@ public class CfDnsClient extends CfBasicHttpClient { * * @param zoneName the name of the DNS zone (e.g., "example.com") * @return a ZoneOperations instance for chaining operations - * @throws CloudflareApiException if the zone cannot be found or accessed + * @throws CloudflareNotFoundException if the zone doesn't exist + * @throws CloudflareApiException if the zone cannot be accessed */ public ZoneOperations zone(String zoneName) throws CloudflareApiException { ZoneEntity zoneEntity = zoneGet(zoneName); + if (zoneEntity == null) { + throw new CloudflareNotFoundException("Zone not found: " + zoneName); + } return new ZoneOperationsImpl(this, zoneEntity); } /** - * Retrieves a list of all zones from the Cloudflare API. + * Retrieves a list of all zones from the Cloudflare API. If there are more zones than fit on one + * page, all pages are fetched. * * @return A list of ZoneEntity objects representing the zones retrieved from the Cloudflare API. * @throws CloudflareApiException If an error occurs during the API request or response handling. */ public List zoneList() throws CloudflareApiException { - return zoneList(PagingRequest.defaultPaging()); + return getAllPages(CfRequest.ZONE_LIST.buildPath(), ZoneMultipleResponse.class, ZONES_PER_PAGE); } /** - * Retrieves a list of all DNS zones using the provided paging request parameters. + * Retrieves a single page of DNS zones using the provided paging request parameters. * * @param pagingRequest the pagination request object containing parameters for paging and * filtering zone data @@ -166,115 +197,136 @@ public class CfDnsClient extends CfBasicHttpClient { * Retrieves detailed information about a specific zone by its name. * * @param name The name of the zone to retrieve information for. - * @return A {@link ZoneEntity} object that contains details of the specified zone. - * @throws CloudflareApiException If an error occurs while making the API request or processing - * the response. + * @return A {@link ZoneEntity} object that contains details of the specified zone, or + * {@code null} if the zone doesn't exist and 'emptyResultThrowsException' is disabled. + * @throws CloudflareNotFoundException If the zone doesn't exist and 'emptyResultThrowsException' + * is enabled. + * @throws CloudflareApiException If an error occurs while making the API request or + * processing the response. */ + @Nullable public ZoneEntity zoneGet(String name) throws CloudflareApiException { String endpoint = CfRequest.ZONE_INFO.buildPath(name); ZoneMultipleResponse response = getRequest(endpoint, ZoneMultipleResponse.class); checkResponse(response, true); - return response.getResult().get(0); + List zones = response.getResult(); + return (zones == null || zones.isEmpty()) ? null : zones.get(0); } /** - * Retrieves a list of DNS records for a specified zone, with optional paging support. + * Retrieves all DNS records for a specified zone. If there are more records than fit on one + * page, all pages are fetched. * - * @param zone The zone entity containing information about the target zone. + * @param zone The zone entity containing information about the target zone. * @return A list of RecordEntity objects representing the DNS records of the specified zone. * @throws CloudflareApiException If an error occurs during the API request or response processing. */ public List recordList(ZoneEntity zone) throws CloudflareApiException { - return recordList(zone, (PagingRequest) null); + return recordList(zone, null); } /** - * Retrieves a list of DNS records for a specified zone, with optional paging support. + * Retrieves DNS records for a specified zone, with optional paging support. * * @param zone The zone entity containing information about the target zone. * @param pagingRequest The paging request containing parameters such as page size and number. + * If {@code null}, all pages are fetched. * @return A list of RecordEntity objects representing the DNS records of the specified zone. * @throws CloudflareApiException If an error occurs during the API request or response processing. */ - public List recordList(ZoneEntity zone, @Nullable PagingRequest pagingRequest) throws CloudflareApiException { - PagingRequest pr = pagingRequest == null ? PagingRequest.defaultPaging() : pagingRequest; - String endpoint = pr.addQueryString(CfRequest.RECORD_LIST.buildPath(zone.getId())); - RecordMultipleResponse resp = getRequest(endpoint, RecordMultipleResponse.class); + public List recordList(ZoneEntity zone, @Nullable PagingRequest pagingRequest) + throws CloudflareApiException { + String path = CfRequest.RECORD_LIST.buildPath(zone.getId()); + if (pagingRequest == null) { + return filterAndSetZoneRecords(zone, null, + getAllPages(path, RecordMultipleResponse.class, RECORDS_PER_PAGE)); + } + RecordMultipleResponse resp = getRequest(pagingRequest.addQueryString(path), RecordMultipleResponse.class); checkResponse(resp); - return resp.getResult(); + return filterAndSetZoneRecords(zone, null, resp.getResult()); } /** - * Retrieves DNS records for the specified second-level domain (SLD) within a zone. - * - * @param zone the zone entity representing the DNS zone to query - * @param sld the second-level domain (SLD) to filter the records - * @return a list of RecordEntity objects that match the specified SLD within the zone - * @throws CloudflareNotFoundException if the specified SLD is not found in the zone - * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API - */ - public List recordList(ZoneEntity zone, String sld) throws CloudflareApiException { - return recordList(zone, sld, (RecordType[]) null); - } - - /** - * Retrieves DNS records for the specified second-level domain (SLD) within a zone. + * Retrieves DNS records for the specified subdomain within a zone. * 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 record types to filter the results. + * @param zone The zone entity containing information about the domain zone. + * @param subdomain The subdomain relative to the zone (e.g. "www" for "www.example.com"), + * or {@link #APEX} for the zone apex. + * @param types Optional DNS record types to filter the results. If none are given, records of + * all types are returned. * @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 CloudflareNotFoundException if no records were found and 'emptyResultThrowsException' + * is enabled * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ - public List recordList(ZoneEntity zone, String sld, @Nullable RecordType... types) + public List recordListBySubdomain(ZoneEntity zone, String subdomain, + @Nullable RecordType... types) throws CloudflareApiException { - String fqdn = buildFqdn(zone, sld); - String endpoint = CfRequest.RECORD_LIST_NAME.buildPath(zone.getId(), fqdn); - RecordMultipleResponse resp = getRequest(endpoint, RecordMultipleResponse.class); - checkResponse(resp, false); - List recs = resp.getResult(); + String fqdn = buildFqdn(zone, subdomain); + String endpoint = addTypeFilter(CfRequest.RECORD_LIST_NAME.buildPath(zone.getId(), fqdn), types); + List recs = getAllPages(endpoint, RecordMultipleResponse.class, RECORDS_PER_PAGE); return filterAndSetZoneRecords(zone, types, recs); } /** - * Retrieves a list of all DNS records for a given zone. - * Optionally, filters by one or more DNS record types. + * Retrieves all DNS records of the given types for a zone. * * @param zone The zone entity containing information about the domain zone. - * @param types Optional parameter specifying one or more DNS record types to filter the results. + * @param types Optional DNS record types to filter the results. If none are given, records of all + * types are returned. * @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 + * @throws CloudflareNotFoundException if no records were found and 'emptyResultThrowsException' + * is enabled + * @throws CloudflareApiException if an error occurs while interacting with the Cloudflare API */ - public List recordList(ZoneEntity zone, RecordType... types) + public List recordListByType(ZoneEntity zone, @Nullable RecordType... types) throws CloudflareApiException { - String endpoint = CfRequest.RECORD_LIST.buildPath(zone.getId()); - RecordMultipleResponse resp = getRequest(endpoint, RecordMultipleResponse.class); - checkResponse(resp, false); - List recs = resp.getResult(); + String endpoint = addTypeFilter(CfRequest.RECORD_LIST.buildPath(zone.getId()), types); + List recs = getAllPages(endpoint, RecordMultipleResponse.class, RECORDS_PER_PAGE); return filterAndSetZoneRecords(zone, types, recs); } /** - * Creates a new DNS record for a given second-level domain (SLD) within the specified zone. + * Creates a new DNS record for a given subdomain within the specified zone. * - * @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). + * @param zone The ZoneEntity representing the DNS zone where the record is to be created. + * @param subdomain The subdomain relative to the zone (e.g. "api" for "api.example.com"), + * or {@link #APEX} for the zone apex. + * @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 record. * @throws CloudflareApiException If an error occurs while communicating with the Cloudflare API * or creating the record. */ - public RecordEntity recordCreateSld(ZoneEntity zone, String sld, int ttl, RecordType type, - String content) throws CloudflareApiException { - String fqdn = buildFqdn(zone, sld); + public RecordEntity recordCreateSubdomain(ZoneEntity zone, String subdomain, int ttl, RecordType type, + String content) throws CloudflareApiException { + String fqdn = buildFqdn(zone, subdomain); return recordCreate(zone, fqdn, ttl, type, content); } + /** + * Creates a new DNS record for a given subdomain within the specified zone. + * + * @param zone The ZoneEntity representing the DNS zone where the record is to be created. + * @param subdomain The subdomain relative to the zone. + * @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. + * @param content The content of the DNS record. + * @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 record. + * @deprecated The name was misleading, use + * {@link #recordCreateSubdomain(ZoneEntity, String, int, RecordType, String)} instead. + */ + @Deprecated(since = "0.6.0", forRemoval = true) + public RecordEntity recordCreateSld(ZoneEntity zone, String subdomain, int ttl, RecordType type, + String content) throws CloudflareApiException { + return recordCreateSubdomain(zone, subdomain, ttl, type, content); + } + /** * Creates a DNS record in the specified DNS zone with the provided details. * @@ -298,18 +350,20 @@ public class CfDnsClient extends CfBasicHttpClient { * @param zone The zone entity where the record will be created. Contains details such as zone * ID. * @param rec The record entity representing the DNS record to be created, including its - * attributes. + * attributes. Read-only attributes (e.g. ID, timestamps) are ignored, the given + * object isn't modified. * @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) throws CloudflareApiException { String endpoint = CfRequest.RECORD_CREATE.buildPath(zone.getId()); - RecordSingleResponse resp = postRequest(endpoint, rec, RecordSingleResponse.class); + RecordEntity payload = writableCopy(rec, false); + RecordSingleResponse resp = postRequest(endpoint, payload, RecordSingleResponse.class); checkResponse(resp); - log.info("Record {} of type {} successful created.", rec.getSld(), rec.getType()); + log.info("Record {} of type {} successful created.", rec.getSubdomain(), rec.getType()); RecordEntity retRec = resp.getResult(); - retRec.setZoneId(zone.getId()); + assignZone(retRec, zone); return retRec; } @@ -325,9 +379,9 @@ public class CfDnsClient extends CfBasicHttpClient { public boolean recordDelete(ZoneEntity zone, RecordEntity rec) throws CloudflareApiException { boolean changed = recordDelete(zone, rec.getId()); if (changed) { - log.debug("Record {} of the type [{}] successful deleted.", rec.getSld(), rec.getType()); + log.debug("Record {} of the type [{}] successful deleted.", rec.getSubdomain(), rec.getType()); } else { - log.warn("Record {} of the type [{}] was not deleted.", rec.getSld(), rec.getType()); + log.warn("Record {} of the type [{}] was not deleted.", rec.getSubdomain(), rec.getType()); } return changed; } @@ -336,8 +390,9 @@ public class CfDnsClient extends CfBasicHttpClient { * 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 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. + * @param id The ID of the DNS record to be deleted. + * @return {@code true} if the API confirms the deletion of the record with the given ID; + * {@code false} otherwise. * @throws CloudflareApiException if there is an issue during the API communication or the request * fails for any reason. */ @@ -345,29 +400,35 @@ public class CfDnsClient extends CfBasicHttpClient { String endpoint = CfRequest.RECORD_DELETE.buildPath(zone.getId(), id); RecordSingleResponse resp = deleteRequest(endpoint, RecordSingleResponse.class); checkResponse(resp); - log.debug("Record id#{} successful deleted.", id); - return resp.getResult().getId().equals(id); + RecordEntity deleted = resp.getResult(); + boolean confirmed = deleted != null && id.equals(deleted.getId()); + if (confirmed) { + log.debug("Record id#{} successfully deleted.", id); + } + return confirmed; } /** - * Updates an existing DNS record in a specified Cloudflare zone. + * Updates an existing DNS record in a specified Cloudflare zone (partial update, attributes + * which are {@code null} remain unchanged). * * @param zone the zone entity containing the ID of the target zone * @param rec the record entity containing the ID of the DNS record to be updated and its updated - * data + * data. Read-only attributes (e.g. timestamps) are ignored, the given object isn't + * modified. * @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) throws CloudflareApiException { - // reset all dates, it causes an API issue - rec.setModifiedOn(null); - rec.setCreatedOn(null); String endpoint = CfRequest.RECORD_UPDATE.buildPath(zone.getId(), rec.getId()); - RecordSingleResponse resp = patchRequest(endpoint, rec, RecordSingleResponse.class); + RecordEntity payload = writableCopy(rec, false); + RecordSingleResponse resp = patchRequest(endpoint, payload, RecordSingleResponse.class); checkResponse(resp); - log.info("Record {} of type {} successful updated.", rec.getSld(), rec.getType()); - return resp.getResult(); + log.info("Record {} of type {} successful updated.", rec.getSubdomain(), rec.getType()); + RecordEntity retRec = resp.getResult(); + assignZone(retRec, zone); + return retRec; } /** @@ -375,16 +436,16 @@ public class CfDnsClient extends CfBasicHttpClient { * specified type exists, it logs this occurrence without throwing an exception. * * @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 subdomain The subdomain relative to the zone for which the records are 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. */ - public void recordDeleteTypeIfExists(ZoneEntity zone, String sld, RecordType... recordTypes) + public void recordDeleteTypeIfExists(ZoneEntity zone, String subdomain, RecordType... recordTypes) throws CloudflareApiException { - String fqdn = buildFqdn(zone, sld); + String fqdn = buildFqdn(zone, subdomain); List recs; try { - recs = recordList(zone, sld, recordTypes); + recs = recordListBySubdomain(zone, subdomain, recordTypes); } catch (CloudflareNotFoundException e) { log.trace("No record of type {} found for domain {}.", recordTypes, fqdn); return; @@ -408,7 +469,8 @@ public class CfDnsClient extends CfBasicHttpClient { * @param postRecords A list of DNS records to be created (POST). This parameter is nullable. * @param putRecords A list of DNS records to be fully replaced (PUT). This parameter is nullable. * @param patchRecords A list of DNS records to be partially updated (PATCH). This parameter is nullable. - * @param deleteRecords A list of DNS records to be deleted (DELETE). This parameter is nullable. + * @param deleteRecords A list of DNS records to be deleted (DELETE), only the IDs are used. This + * parameter is nullable. * @return The resulting {@link BatchEntry} containing the processed records after the batch operation. * @throws CloudflareApiException If an error occurs while communicating with the Cloudflare API. */ @@ -416,18 +478,18 @@ public class CfDnsClient extends CfBasicHttpClient { @Nullable List patchRecords, @Nullable List deleteRecords) throws CloudflareApiException { BatchEntry batchEntry = new BatchEntry(); - // build 'clean' record entries + // build 'clean' record entries, the given records aren't modified if (postRecords != null) { - batchEntry.setPosts(cleanRecordsForPostOrPut(postRecords)); + batchEntry.setPosts(postRecords.stream().map(rec -> writableCopy(rec, false)).toList()); } if (putRecords != null) { - batchEntry.setPuts(cleanRecordsForPostOrPut(putRecords)); + batchEntry.setPuts(putRecords.stream().map(rec -> writableCopy(rec, true)).toList()); } if (patchRecords != null) { - batchEntry.setPatches(cleanRecordsForPatch(patchRecords)); + batchEntry.setPatches(patchRecords.stream().map(rec -> writableCopy(rec, true)).toList()); } if (deleteRecords != null) { - batchEntry.setDeletes(cleanRecordsForDelete(deleteRecords)); + batchEntry.setDeletes(deleteRecords.stream().map(CfDnsClient::idOnly).toList()); } String endpoint = CfRequest.RECORD_BATCH.buildPath(zone.getId()); @@ -436,21 +498,27 @@ public class CfDnsClient extends CfBasicHttpClient { // set zone id BatchEntry result = resp.getResult(); - setZoneIdForBatchResults(result, zone.getId()); + setZoneForBatchResults(result, zone); return result; } - private List filterAndSetZoneRecords(ZoneEntity zone, @Nullable RecordType[] types, List recs) + private List filterAndSetZoneRecords(ZoneEntity zone, @Nullable RecordType[] types, + @Nullable List recs) throws CloudflareNotFoundException { + if (recs == null) { + recs = List.of(); + } List filtered; if (types != null && types.length > 0) { - Set allowedTypes = new HashSet<>(Arrays.asList(types)); + Set allowedTypes = Arrays.stream(types).filter(Objects::nonNull) + .map(RecordType::getType).collect(Collectors.toSet()); filtered = recs.stream() - .filter(rec -> allowedTypes.contains(RecordType.valueOf(rec.getType()))).toList(); + .filter(rec -> allowedTypes.contains(rec.getType())) + .collect(Collectors.toCollection(ArrayList::new)); } else { filtered = new ArrayList<>(recs); } - filtered.forEach(rec -> rec.setZoneId(zone.getId())); + filtered.forEach(rec -> assignZone(rec, zone)); // special exception for an empty result, normally it's done in the RecordValidator if (filtered.isEmpty() && emptyResultThrowsException) { @@ -460,35 +528,87 @@ public class CfDnsClient extends CfBasicHttpClient { } - private List cleanRecordsForPostOrPut(List records) { - List cleaned = new ArrayList<>(); - records.forEach( - rec -> cleaned.add(RecordEntity.build(rec.getId(), rec.getSld(), rec.getType(), rec.getTtl(), rec.getContent()))); - return cleaned; - } - - private List cleanRecordsForPatch(List records) { - List cleaned = new ArrayList<>(); - records.forEach(rec -> cleaned.add(RecordEntity.build(rec.getId(), rec.getContent()))); - return cleaned; - } - - private List cleanRecordsForDelete(List records) { - List cleaned = new ArrayList<>(); - records.forEach( - rec -> cleaned.add(RecordEntity.build(rec.getId(), rec.getSld(), rec.getType(), null, rec.getContent()))); - return cleaned; - } - - private void setZoneIdForBatchResults(BatchEntry result, String zoneId) { - if (result.getPosts() != null) { - result.getPosts().forEach(rec -> rec.setZoneId(zoneId)); + /** + * Creates a copy of the record containing only the attributes which can be written to the API. + * Read-only attributes like timestamps, zone info, 'proxiable' or 'locked' are omitted. + */ + private static RecordEntity writableCopy(RecordEntity rec, boolean withId) { + RecordEntity copy = new RecordEntity(); + if (withId) { + copy.setId(rec.getId()); } - if (result.getPuts() != null) { - result.getPuts().forEach(rec -> rec.setZoneId(zoneId)); + copy.setName(rec.getName()); + copy.setType(rec.getType()); + copy.setContent(rec.getContent()); + copy.setTtl(rec.getTtl()); + copy.setProxied(rec.getProxied()); + copy.setPriority(rec.getPriority()); + copy.setComment(rec.getComment()); + copy.setTags(rec.getTags() == null ? null : new ArrayList<>(rec.getTags())); + copy.setData(rec.getData() == null ? null : new LinkedHashMap<>(rec.getData())); + return copy; + } + + private static RecordEntity idOnly(RecordEntity rec) { + RecordEntity copy = new RecordEntity(); + copy.setId(rec.getId()); + return copy; + } + + /** + * Adds the server-side type filter to the endpoint. The API supports only one type, so the + * filter is only added if exactly one type is given. Multiple types are filtered client-side. + */ + private static String addTypeFilter(String endpoint, @Nullable RecordType[] types) { + if (types == null || types.length != 1 || types[0] == null) { + return endpoint; } - if (result.getPatches() != null) { - result.getPatches().forEach(rec -> rec.setZoneId(zoneId)); + return endpoint + (endpoint.contains("?") ? "&" : "?") + "type=" + types[0].getType(); + } + + private void setZoneForBatchResults(@Nullable BatchEntry result, ZoneEntity zone) { + if (result == null) { + return; + } + for (List recs : Arrays.asList(result.getPosts(), result.getPuts(), + result.getPatches(), result.getDeletes())) { + if (recs != null) { + recs.forEach(rec -> assignZone(rec, zone)); + } + } + } + + private static void assignZone(@Nullable RecordEntity rec, ZoneEntity zone) { + if (rec != null) { + rec.setZoneId(zone.getId()); + rec.setZoneName(zone.getName()); + } + } + + /** + * Fetches all pages of a paginated endpoint and returns the combined results. + * + * @param endpoint the endpoint path, may already contain a query string + * @param responseType the expected response type + * @param perPage the page size to request + */ + private > List getAllPages( + String endpoint, Class responseType, int perPage) throws CloudflareApiException { + List all = new ArrayList<>(); + int page = 1; + while (true) { + String pagedEndpoint = PagingRequest.of(page, perPage).addQueryString(endpoint); + R resp = getRequest(pagedEndpoint, responseType); + checkResponse(resp); + List result = resp.getResult(); + if (result != null) { + all.addAll(result); + } + ResultInfo info = resp.getResultInfo(); + if (info == null || result == null || result.isEmpty() || page >= info.totalPages()) { + return all; + } + page++; } } diff --git a/src/main/java/codes/thischwa/cf/CloudflareApiException.java b/src/main/java/codes/thischwa/cf/CloudflareApiException.java index 30e83ef..0ba91f2 100644 --- a/src/main/java/codes/thischwa/cf/CloudflareApiException.java +++ b/src/main/java/codes/thischwa/cf/CloudflareApiException.java @@ -1,14 +1,34 @@ package codes.thischwa.cf; +import codes.thischwa.cf.model.ResponseResultInfo; import java.io.Serial; +import java.util.List; /** * Represents a custom exception for errors encountered while interacting with the Cloudflare API. + * + *

If the error was caused by an API response, {@link #getStatusCode()} returns the HTTP status + * code and {@link #getErrors()} the errors reported by Cloudflare. */ public class CloudflareApiException extends Exception { + /** + * Value of {@link #getStatusCode()} if the exception was not caused by an HTTP response. + */ + public static final int NO_STATUS_CODE = -1; + @Serial - private static final long serialVersionUID = 1L; + private static final long serialVersionUID = 2L; + + /** + * The HTTP status code of the response, or {@link #NO_STATUS_CODE}. + */ + private final int statusCode; + + /** + * The errors reported by Cloudflare. Transient, because the error class isn't serializable. + */ + private final transient List errors; /** * Constructs a new CloudflareApiException with the specified detail message. @@ -16,7 +36,7 @@ public class CloudflareApiException extends Exception { * @param message the detail message, which provides more information about the exception. */ public CloudflareApiException(String message) { - super(message); + this(message, NO_STATUS_CODE, null); } /** @@ -29,5 +49,40 @@ public class CloudflareApiException extends Exception { */ public CloudflareApiException(String message, Throwable cause) { super(message, cause); + this.statusCode = NO_STATUS_CODE; + this.errors = List.of(); + } + + /** + * Constructs a new CloudflareApiException caused by an API response. + * + * @param message the detail message + * @param statusCode the HTTP status code of the response, or {@link #NO_STATUS_CODE} + * @param errors the errors reported by Cloudflare, may be {@code null} + */ + public CloudflareApiException(String message, int statusCode, + List errors) { + super(message); + this.statusCode = statusCode; + this.errors = errors == null ? List.of() : List.copyOf(errors); + } + + /** + * Returns the HTTP status code of the response that caused this exception. + * + * @return the HTTP status code, or {@link #NO_STATUS_CODE} if the exception wasn't caused by an + * HTTP response + */ + public int getStatusCode() { + return statusCode; + } + + /** + * Returns the errors reported by Cloudflare. + * + * @return an unmodifiable list of errors, never {@code null} + */ + public List getErrors() { + return errors == null ? List.of() : errors; } } diff --git a/src/main/java/codes/thischwa/cf/CloudflareNotFoundException.java b/src/main/java/codes/thischwa/cf/CloudflareNotFoundException.java index c52e592..b1972af 100644 --- a/src/main/java/codes/thischwa/cf/CloudflareNotFoundException.java +++ b/src/main/java/codes/thischwa/cf/CloudflareNotFoundException.java @@ -1,14 +1,21 @@ package codes.thischwa.cf; +import codes.thischwa.cf.model.ResponseResultInfo; +import java.io.Serial; +import java.util.List; + /** * This exception is thrown to indicate that a requested resource was not found during interaction * with the Cloudflare API. * - *

It extends {@link CloudflareApiException} to provide specific errors related to situations - * where Cloudflare responds with a "not found" operation. + *

It is thrown if Cloudflare responds with HTTP status 404, or if a result is empty and + * 'emptyResultThrowsException' is enabled. */ public class CloudflareNotFoundException extends CloudflareApiException { + @Serial + private static final long serialVersionUID = 1L; + /** * Constructs a new CloudflareNotFoundException with the specified detail message. * @@ -18,4 +25,16 @@ public class CloudflareNotFoundException extends CloudflareApiException { public CloudflareNotFoundException(String message) { super(message); } + + /** + * Constructs a new CloudflareNotFoundException caused by an API response. + * + * @param message the detail message + * @param statusCode the HTTP status code of the response + * @param errors the errors reported by Cloudflare, may be {@code null} + */ + public CloudflareNotFoundException(String message, int statusCode, + List errors) { + super(message, statusCode, errors); + } } diff --git a/src/main/java/codes/thischwa/cf/ResponseValidator.java b/src/main/java/codes/thischwa/cf/ResponseValidator.java index ae5de03..4ffba4f 100644 --- a/src/main/java/codes/thischwa/cf/ResponseValidator.java +++ b/src/main/java/codes/thischwa/cf/ResponseValidator.java @@ -1,8 +1,8 @@ package codes.thischwa.cf; +import codes.thischwa.cf.model.AbstractMultipleResponse; import codes.thischwa.cf.model.AbstractResponse; import codes.thischwa.cf.model.AbstractSingleResponse; -import codes.thischwa.cf.model.RecordMultipleResponse; import codes.thischwa.cf.model.ResponseResultInfo; import java.util.stream.Collectors; @@ -16,7 +16,7 @@ import java.util.stream.Collectors; * metadata. If the response indicates failure, an exception is thrown with descriptive error * messages. *

  • It validates the number of results in the API response payload to detect unexpected counts. - * For {@link RecordMultipleResponse}, it checks if results are empty or if more than one result + * For {@link AbstractMultipleResponse}, it checks if results are empty or if more than one result * was returned when a single result was expected. For {@link AbstractSingleResponse}, it checks * if the result is null. Depending on the parameter 'emptyResultThrowsException', an exception * will be triggered or an empty/null result will be returned. @@ -45,16 +45,16 @@ class ResponseValidator { private void validateResultCount(AbstractResponse resp, boolean singleResultExpected) throws CloudflareApiException { - if (resp instanceof RecordMultipleResponse respMulti) { + if (resp instanceof AbstractMultipleResponse respMulti) { validateMultipleResponse(respMulti, singleResultExpected); } else if (resp instanceof AbstractSingleResponse respSingle) { validateSingleResponse(respSingle); } } - private void validateMultipleResponse(RecordMultipleResponse response, boolean singleResultExpected) + private void validateMultipleResponse(AbstractMultipleResponse response, boolean singleResultExpected) throws CloudflareApiException { - int totalCount = response.getResultInfo().totalCount(); + int totalCount = getTotalCount(response); if (singleResultExpected && totalCount > 1) { throw new CloudflareApiException("Unexpected result count: " + totalCount); } @@ -63,6 +63,17 @@ class ResponseValidator { } } + /** + * Determines the total count of the results. Falls back to the size of the result list if the + * response contains no result info. + */ + private static int getTotalCount(AbstractMultipleResponse response) { + if (response.getResultInfo() != null) { + return response.getResultInfo().totalCount(); + } + return response.getResult() == null ? 0 : response.getResult().size(); + } + private void validateSingleResponse(AbstractSingleResponse response) throws CloudflareNotFoundException { if (emptyResultThrowsException && response.getResult() == null) { diff --git a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java index da9a5b7..d9877a0 100644 --- a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java +++ b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java @@ -15,50 +15,49 @@ public class RecordOperationsImpl implements RecordOperations { private final CfDnsClient client; private final ZoneEntity zone; - private final String sld; + private final String subdomain; private final RecordType[] types; /** * Constructs a RecordOperationsImpl instance. * - * @param client the CfDnsClient instance to use for operations - * @param zone the ZoneEntity representing the DNS zone - * @param sld the subdomain (second-level domain) name - * @param types optional array of RecordType to filter by + * @param client the CfDnsClient instance to use for operations + * @param zone the ZoneEntity representing the DNS zone + * @param subdomain the subdomain relative to the zone, or "@" for the zone apex + * @param types optional array of RecordType to filter by */ - public RecordOperationsImpl(CfDnsClient client, ZoneEntity zone, String sld, @Nullable RecordType[] types) { + public RecordOperationsImpl(CfDnsClient client, ZoneEntity zone, String subdomain, @Nullable RecordType[] types) { this.client = client; this.zone = zone; - this.sld = sld; + this.subdomain = subdomain; this.types = types; } @Override public List get() throws CloudflareApiException { - return client.recordList(zone, sld, types); + return client.recordListBySubdomain(zone, subdomain, types); } @Override public RecordEntity create(RecordType type, String content, int ttl) throws CloudflareApiException { - return client.recordCreateSld(zone, sld, ttl, type, content); + return client.recordCreateSubdomain(zone, subdomain, ttl, type, content); } @Override public RecordEntity update(String newContent) throws CloudflareApiException { List recs = get(); if (recs.isEmpty()) { - throw new CloudflareApiException("No recs found to update for subdomain: " + sld); + throw new CloudflareApiException("No recs found to update for subdomain: " + subdomain); } if (recs.size() > 1) { throw new CloudflareApiException("Multiple recs found. Please use recordUpdate() directly for precise control."); } - RecordEntity rec = recs.get(0); - rec.setContent(newContent); - return client.recordUpdate(zone, rec); + // partial update: only the content is changed + return client.recordUpdate(zone, RecordEntity.build(recs.get(0).getId(), newContent)); } @Override public void delete(RecordType... types) throws CloudflareApiException { - client.recordDeleteTypeIfExists(zone, sld, types); + client.recordDeleteTypeIfExists(zone, subdomain, types); } } diff --git a/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java b/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java index 2c8c21e..44bf4f9 100644 --- a/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java +++ b/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java @@ -13,26 +13,26 @@ public interface ZoneOperations { /** * Selects a record (subdomain) within the zone for further operations. * - * @param sld the second-level domain (subdomain) name + * @param subdomain the subdomain relative to the zone (e.g. "www"), or "@" for the zone apex * @return a RecordOperations instance for chaining record-specific operations * @throws CloudflareApiException if the zone cannot be found or accessed */ - RecordOperations getRecord(String sld) throws CloudflareApiException; + RecordOperations getRecord(String subdomain) throws CloudflareApiException; /** * Selects a record with specific types within the zone for further operations. * - * @param sld the second-level domain (subdomain) name - * @param types optional DNS record types to filter by + * @param subdomain the subdomain relative to the zone (e.g. "www"), or "@" for the zone apex + * @param types optional DNS record types to filter by * @return a RecordOperations instance for chaining record-specific operations * @throws CloudflareApiException if the zone cannot be found or accessed */ - RecordOperations getRecord(String sld, @Nullable RecordType... types) throws CloudflareApiException; + RecordOperations getRecord(String subdomain, @Nullable RecordType... types) throws CloudflareApiException; /** * Lists all DNS records within the zone, optionally filtered by types. * - * @param types optional DNS record types to filter by + * @param types optional DNS record types to filter by * @return a list of RecordEntity objects matching the criteria * @throws CloudflareApiException if an error occurs while retrieving records */ diff --git a/src/main/java/codes/thischwa/cf/fluent/ZoneOperationsImpl.java b/src/main/java/codes/thischwa/cf/fluent/ZoneOperationsImpl.java index fd78f28..fd61510 100644 --- a/src/main/java/codes/thischwa/cf/fluent/ZoneOperationsImpl.java +++ b/src/main/java/codes/thischwa/cf/fluent/ZoneOperationsImpl.java @@ -28,17 +28,17 @@ public class ZoneOperationsImpl implements ZoneOperations { } @Override - public RecordOperations getRecord(String sld) throws CloudflareApiException { - return new RecordOperationsImpl(client, zone, sld, null); + public RecordOperations getRecord(String subdomain) throws CloudflareApiException { + return new RecordOperationsImpl(client, zone, subdomain, null); } @Override - public RecordOperations getRecord(String sld, @Nullable RecordType... types) throws CloudflareApiException { - return new RecordOperationsImpl(client, zone, sld, types); + public RecordOperations getRecord(String subdomain, @Nullable RecordType... types) throws CloudflareApiException { + return new RecordOperationsImpl(client, zone, subdomain, types); } @Override public List list(@Nullable RecordType... types) throws CloudflareApiException { - return client.recordList(zone, types); + return client.recordListByType(zone, types); } } diff --git a/src/main/java/codes/thischwa/cf/model/RecordEntity.java b/src/main/java/codes/thischwa/cf/model/RecordEntity.java index 7fb32d3..a2bd5ec 100644 --- a/src/main/java/codes/thischwa/cf/model/RecordEntity.java +++ b/src/main/java/codes/thischwa/cf/model/RecordEntity.java @@ -1,6 +1,10 @@ package codes.thischwa.cf.model; -import java.time.LocalDateTime; +import com.fasterxml.jackson.annotation.JsonIgnore; +import java.time.Instant; +import java.util.List; +import java.util.Locale; +import java.util.Map; import lombok.Data; import lombok.EqualsAndHashCode; import org.jetbrains.annotations.Nullable; @@ -16,9 +20,12 @@ import org.jetbrains.annotations.Nullable; *
  • 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. + *
  • Priority, required for MX, SRV and URI records. + *
  • Structured data, required for e.g. SRV, CAA, LOC or TLSA records instead of content. + *
  • An optional comment and tags. *
  • A locked status to indicate the immutability of the record. *
  • Zone-specific metadata including zone ID and name. - *
  • Timestamps for creation and modification. + *
  • Timestamps for creation and modification (UTC). * * *

    Provides a static factory method {@code build} for creating a DNS record with specific @@ -27,21 +34,44 @@ import org.jetbrains.annotations.Nullable; @EqualsAndHashCode(callSuper = true) @Data public class RecordEntity extends AbstractEntity { + private static final String APEX = "@"; + private String type; private String name; private String content; private Boolean proxiable; private Boolean proxied; private Integer ttl; + /** + * Priority of the record, required for MX, SRV and URI records. + */ + @Nullable + private Integer priority; + /** + * Comment of the record, only used by Cloudflare. + */ + @Nullable + private String comment; + /** + * Custom tags of the record in the form "name:value", only used by Cloudflare. + */ + @Nullable + private List tags; + /** + * Structured content of the record, e.g. for SRV records the keys "weight", "port" and "target". + * The keys are the same as in the Cloudflare API. + */ + @Nullable + private Map data; private Boolean locked; @Nullable private String zoneId; @Nullable private String zoneName; @Nullable - private LocalDateTime modifiedOn; + private Instant modifiedOn; @Nullable - private LocalDateTime createdOn; + private Instant createdOn; /** * Initializes a new instance of the RecordEntity class and invokes the parent constructor from @@ -114,22 +144,31 @@ public class RecordEntity extends AbstractEntity { } /** - * 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. + * Retrieves the subdomain of the DNS record, i.e. the record name relative to its zone. * - * @return the short name of the DNS record (substring before the first dot), - * or the full name if no dot is present + *

    If the zone name is known, the zone name is stripped from the record name, e.g. + * {@code my.sub.example.com} results in {@code my.sub}. A record at the zone apex results in + * {@code "@"}. If the zone name is unknown, only the substring before the first dot is returned. + * + * @return the short name of the DNS record, {@code "@"} for the zone apex, or the full name if + * no dot is present */ - public String getSld() { + @JsonIgnore + @Nullable + public String getSubdomain() { if (name == null) { return null; } - if (zoneName != null && name.endsWith(zoneName)) { - int zoneNameLength = zoneName.length(); - int dotSeparatorLength = 1; - return name.substring(0, name.length() - zoneNameLength - dotSeparatorLength); + if (zoneName != null && !zoneName.isEmpty()) { + String lowerName = name.toLowerCase(Locale.ROOT); + String lowerZone = zoneName.toLowerCase(Locale.ROOT); + if (lowerName.equals(lowerZone)) { + return APEX; + } + if (lowerName.endsWith("." + lowerZone)) { + return name.substring(0, name.length() - zoneName.length() - 1); + } } int firstDotPosition = name.indexOf('.'); @@ -139,4 +178,17 @@ public class RecordEntity extends AbstractEntity { return name; } -} \ No newline at end of file + + /** + * Retrieves the subdomain of the DNS record. + * + * @return the subdomain of the DNS record + * @deprecated The name was misleading, use {@link #getSubdomain()} instead. + */ + @Deprecated(since = "0.6.0", forRemoval = true) + @JsonIgnore + @Nullable + public String getSld() { + return getSubdomain(); + } +} diff --git a/src/main/java/codes/thischwa/cf/model/ZoneEntity.java b/src/main/java/codes/thischwa/cf/model/ZoneEntity.java index 0919e84..020bd59 100644 --- a/src/main/java/codes/thischwa/cf/model/ZoneEntity.java +++ b/src/main/java/codes/thischwa/cf/model/ZoneEntity.java @@ -1,6 +1,6 @@ package codes.thischwa.cf.model; -import java.time.LocalDateTime; +import java.time.Instant; import java.util.Set; import lombok.Data; import lombok.EqualsAndHashCode; @@ -15,7 +15,7 @@ import lombok.EqualsAndHashCode; *

  • Zone name. *
  • Development mode status. *
  • Active and original name servers linked to the zone. - *
  • Timestamps indicating when the zone was created, modified, or activated. + *
  • Timestamps (UTC) indicating when the zone was created, modified, or activated. *
  • Current operational status of the zone (e.g., active, inactive). *
  • Boolean flag indicating whether the zone is paused. *
  • Zone type, representing the nature of the DNS zone (e.g., full, partial). @@ -31,9 +31,9 @@ public class ZoneEntity extends AbstractEntity { private Integer developmentMode; private Set nameServers; private Set originalNameServers; - private LocalDateTime createdOn; - private LocalDateTime modifiedOn; - private LocalDateTime activatedOn; + private Instant createdOn; + private Instant modifiedOn; + private Instant activatedOn; private String status; private Boolean paused; private String type; diff --git a/src/test/java/codes/thischwa/cf/CfBasicHttpClientErrorTest.java b/src/test/java/codes/thischwa/cf/CfBasicHttpClientErrorTest.java new file mode 100644 index 0000000..a483b1f --- /dev/null +++ b/src/test/java/codes/thischwa/cf/CfBasicHttpClientErrorTest.java @@ -0,0 +1,128 @@ +package codes.thischwa.cf; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import codes.thischwa.cf.model.ZoneEntity; +import com.sun.net.httpserver.HttpServer; +import java.io.IOException; +import java.io.OutputStream; +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +/** + * Tests the error handling of {@link CfBasicHttpClient} against a local HTTP server. + */ +class CfBasicHttpClientErrorTest { + + private static final String ZONE_JSON = """ + {"success":true,"errors":[],"messages":[], + "result_info":{"page":1,"per_page":50,"total_pages":1,"count":1,"total_count":1}, + "result":[{"id":"zone1","name":"example.com","created_on":"2025-01-20T08:56:34.736214Z"}]} + """; + + private HttpServer server; + private CfDnsClient client; + private final AtomicInteger requestCount = new AtomicInteger(); + private volatile int status; + private volatile String body; + + @BeforeEach + void setUp() throws IOException { + server = HttpServer.create(new InetSocketAddress("localhost", 0), 0); + server.createContext("/", exchange -> { + requestCount.incrementAndGet(); + byte[] bytes = body.getBytes(StandardCharsets.UTF_8); + exchange.sendResponseHeaders(status, bytes.length); + try (OutputStream out = exchange.getResponseBody()) { + out.write(bytes); + } + }); + server.start(); + client = new CfDnsClientBuilder() + .withApiTokenAuth("test-token") + .withBaseUrl("http://localhost:" + server.getAddress().getPort()) + .build(); + } + + @AfterEach + void tearDown() throws IOException { + client.close(); + server.stop(0); + } + + private void respond(int status, String body) { + this.status = status; + this.body = body; + } + + @Test + void apiErrorContainsStatusCodeAndErrors() { + respond(400, """ + {"success":false,"errors":[{"code":1004,"message":"DNS Validation Error"}],"messages":[],"result":null} + """); + + CloudflareApiException e = assertThrows(CloudflareApiException.class, () -> client.zoneList()); + + assertEquals(CloudflareApiException.class, e.getClass()); + assertEquals(400, e.getStatusCode()); + assertEquals(1, e.getErrors().size()); + assertEquals(1004, e.getErrors().get(0).getCode()); + assertTrue(e.getMessage().contains("DNS Validation Error"), e.getMessage()); + } + + @Test + void status404ThrowsNotFound() { + respond(404, """ + {"success":false,"errors":[{"code":81044,"message":"Record does not exist."}],"messages":[],"result":null} + """); + ZoneEntity zone = new ZoneEntity(); + zone.setId("zone1"); + zone.setName("example.com"); + + CloudflareApiException e = assertThrows(CloudflareApiException.class, + () -> client.recordDelete(zone, "0123456789abcdef0123456789abcdef")); + + assertInstanceOf(CloudflareNotFoundException.class, e); + assertEquals(404, e.getStatusCode()); + assertEquals(81044, e.getErrors().get(0).getCode()); + } + + @Test + void nonJsonErrorResponseKeepsStatusCode() { + respond(502, "Bad Gateway"); + + CloudflareApiException e = assertThrows(CloudflareApiException.class, () -> client.zoneList()); + + assertEquals(502, e.getStatusCode()); + assertTrue(e.getErrors().isEmpty()); + assertTrue(e.getMessage().contains("502"), e.getMessage()); + } + + @Test + void successWithTimestampsAndReusedClient() throws CloudflareApiException { + respond(200, ZONE_JSON); + + ZoneEntity zone = client.zoneGet("example.com"); + assertNotNull(zone); + assertEquals("2025-01-20T08:56:34.736214Z", zone.getCreatedOn().toString()); + + // the same client instance can be used for multiple requests + assertEquals(1, client.zoneList().size()); + assertEquals(2, requestCount.get()); + } + + @Test + void exceptionWithoutResponseHasNoStatusCode() { + CloudflareApiException e = new CloudflareApiException("test"); + assertEquals(CloudflareApiException.NO_STATUS_CODE, e.getStatusCode()); + assertTrue(e.getErrors().isEmpty()); + } +} diff --git a/src/test/java/codes/thischwa/cf/CfBasicHttpClientTest.java b/src/test/java/codes/thischwa/cf/CfBasicHttpClientTest.java index 0c0e6cd..68a5ebf 100644 --- a/src/test/java/codes/thischwa/cf/CfBasicHttpClientTest.java +++ b/src/test/java/codes/thischwa/cf/CfBasicHttpClientTest.java @@ -1,7 +1,7 @@ package codes.thischwa.cf; import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -79,10 +79,10 @@ class CfBasicHttpClientTest { }); assertNotNull(exception); - assertTrue(exception.getMessage().contains("Unexpected error")); - Throwable cause = exception.getCause(); - assertInstanceOf(CloudflareApiException.class, cause); - assertTrue(cause.getMessage().contains("No route for that URI"), "Expected error message: No route for that URI, but it was: " + cause.getMessage()); + // the API error must not be wrapped into a generic "Unexpected error" + assertTrue(exception.getMessage().contains("No route for that URI"), + "Expected error message: No route for that URI, but it was: " + exception.getMessage()); + assertNull(exception.getCause()); } @Test diff --git a/src/test/java/codes/thischwa/cf/CfClientPenTest.java b/src/test/java/codes/thischwa/cf/CfClientPenTest.java index 82f0186..1bae42e 100644 --- a/src/test/java/codes/thischwa/cf/CfClientPenTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientPenTest.java @@ -56,11 +56,11 @@ public class CfClientPenTest { "doesnotexist", "abcdef12345", "unwahrscheinlich-" + System.currentTimeMillis()); for (String sld : syntacticallyInvalidSlds) { - assertThrows(IllegalArgumentException.class, () -> client.recordList(zone, sld), + assertThrows(IllegalArgumentException.class, () -> client.recordListBySubdomain(zone, sld), "Should throw IllegalArgumentException for invalid SLD '" + sld + "'"); } for (String sld : syntacticallyValidOrNotAllowedFromCloudflare) { - assertThrows(CloudflareNotFoundException.class, () -> client.recordList(zone, sld), + assertThrows(CloudflareNotFoundException.class, () -> client.recordListBySubdomain(zone, sld), "Should throw CloudflareNotFoundException for valid but non-existing SLD '" + sld + "'"); } } diff --git a/src/test/java/codes/thischwa/cf/CfClientTest.java b/src/test/java/codes/thischwa/cf/CfClientTest.java index 882e9f6..b6a396f 100644 --- a/src/test/java/codes/thischwa/cf/CfClientTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientTest.java @@ -44,7 +44,7 @@ public class CfClientTest { @Test void testUnknownSld() throws Exception { ZoneEntity zone = client.zoneGet(ZONE_STR); - assertThrows(CloudflareNotFoundException.class, () -> client.recordList(zone, "unknown", RecordType.A)); + assertThrows(CloudflareNotFoundException.class, () -> client.recordListBySubdomain(zone, "unknown", RecordType.A)); } @Test @@ -58,13 +58,13 @@ public class CfClientTest { RecordEntity record = RecordEntity.build(SLD_STR, RecordType.A, TTL, "127.0.0.1"); RecordEntity createdRecord = client.recordCreate(zone, record); assertNotNull(createdRecord.getId()); - assertEquals(SLD_STR, createdRecord.getSld()); + assertEquals(SLD_STR, createdRecord.getSubdomain()); assertEquals(RecordType.A.getType(), createdRecord.getType()); assertEquals(TTL, createdRecord.getTtl()); assertEquals("127.0.0.1", createdRecord.getContent()); assertNotNull(createdRecord.getCreatedOn()); - List records = client.recordList(zone, SLD_STR, RecordType.A); + List records = client.recordListBySubdomain(zone, SLD_STR, RecordType.A); assertEquals(1, records.size()); RecordEntity fetchedRecord = records.get(0); assertEquals(createdRecord.getId(), fetchedRecord.getId()); @@ -79,14 +79,14 @@ public class CfClientTest { RecordEntity createdRecordAAAA = client.recordCreate(zone, recordAAAA); assertNotNull(createdRecordA.getId()); assertNotNull(createdRecordAAAA.getId()); - assertEquals(SLD_STR, createdRecordA.getSld()); - assertEquals(SLD_STR, createdRecordAAAA.getSld()); + assertEquals(SLD_STR, createdRecordA.getSubdomain()); + assertEquals(SLD_STR, createdRecordAAAA.getSubdomain()); assertEquals(RecordType.A.getType(), createdRecordA.getType()); assertEquals(RecordType.AAAA.getType(), createdRecordAAAA.getType()); client.recordDeleteTypeIfExists(zone, SLD_STR, RecordType.A, RecordType.AAAA); assertThrows(CloudflareNotFoundException.class, - () -> client.recordList(zone, SLD_STR, RecordType.A, RecordType.AAAA)); + () -> client.recordListBySubdomain(zone, SLD_STR, RecordType.A, RecordType.AAAA)); } finally { // cleanup in case of failures during test try { @@ -114,7 +114,7 @@ public class CfClientTest { assertEquals(1, zList.size()); assertThrows(CloudflareNotFoundException.class, - () -> client.recordList(zList.get(0), "not-existing")); + () -> client.recordListBySubdomain(zList.get(0), "not-existing")); } @Test @@ -149,7 +149,7 @@ public class CfClientTest { client.recordCreate(z, RecordEntity.build(domain, RecordType.A, TTL, "130.0.0.3")); assertNotNull(createdRe1.getId()); assertEquals(randomSld + "." + ZONE_STR, createdRe1.getName()); - assertEquals(randomSld, createdRe1.getSld()); + assertEquals(randomSld, createdRe1.getSubdomain()); assertEquals(RecordType.A.getType(), createdRe1.getType()); assertEquals(z.getId(), createdRe1.getZoneId()); assertEquals(TTL, createdRe1.getTtl()); @@ -158,15 +158,15 @@ public class CfClientTest { assertNotNull(createdRe1.getModifiedOn()); // verify recordList for A - List aRecords = client.recordList(z, randomSld, RecordType.A); + List aRecords = client.recordListBySubdomain(z, randomSld, RecordType.A); assertEquals(1, aRecords.size()); r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); - // create AAAA record using recordCreateSld + // create AAAA record using recordCreateSubdomain createdRe2 = - client.recordCreateSld(z, randomSld, TTL, RecordType.AAAA, "2a0a:4cc0:c0:2e4::1"); - List aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); + client.recordCreateSubdomain(z, randomSld, TTL, RecordType.AAAA, "2a0a:4cc0:c0:2e4::1"); + List aaaaRecords = client.recordListBySubdomain(z, randomSld, RecordType.AAAA); assertEquals(1, aaaaRecords.size()); r = aaaaRecords.get(0); assertEquals(z.getId(), r.getZoneId()); @@ -174,7 +174,7 @@ public class CfClientTest { assertEquals(RecordType.AAAA.getType(), r.getType()); // test recordList - List rList = client.recordList(z, randomSld); + List rList = client.recordListBySubdomain(z, randomSld); assertEquals(2, rList.size()); for (RecordEntity re : rList) { assertEquals(z.getId(), re.getZoneId()); @@ -196,7 +196,7 @@ public class CfClientTest { fullList.stream().allMatch(re -> re.getType().equals(RecordType.A.getType()) || re.getType().equals(RecordType.AAAA.getType()))); // test recordList with types without SLD - List aList = client.recordList(z, RecordType.A); + List aList = client.recordListByType(z, RecordType.A); assertFalse(aList.isEmpty()); assertTrue(aList.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); assertTrue(aList.stream().noneMatch(re -> re.getId().equals(createdRe2.getId()))); @@ -210,13 +210,13 @@ public class CfClientTest { // update AAAA record createdRe2.setContent("2a0a:4cc0:c0:2e4::2"); client.recordUpdate(z, createdRe2); - aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); + aaaaRecords = client.recordListBySubdomain(z, randomSld, RecordType.AAAA); assertEquals(1, aaaaRecords.size()); r = aaaaRecords.get(0); assertEquals("2a0a:4cc0:c0:2e4::2", r.getContent()); // verify A record still intact - aRecords = client.recordList(z, randomSld, RecordType.A); + aRecords = client.recordListBySubdomain(z, randomSld, RecordType.A); assertEquals(1, aRecords.size()); r = aRecords.get(0); assertEquals("130.0.0.3", r.getContent()); @@ -224,12 +224,12 @@ public class CfClientTest { // delete AAAA record and verify it's gone assertTrue(client.recordDelete(z, createdRe2)); assertThrows(CloudflareNotFoundException.class, - () -> client.recordList(z, randomSld, RecordType.AAAA)); + () -> client.recordListBySubdomain(z, randomSld, RecordType.AAAA)); // 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)); + () -> client.recordListBySubdomain(z, randomSld, RecordType.A)); } finally { // cleanup in case of failures during test try { @@ -303,7 +303,7 @@ public class CfClientTest { // Verify only the first 2 records for (int i = 0; i < 2; i++) { - List records1 = client.recordList(zone, sldNames.get(i), RecordType.A); + List records1 = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); assertEquals(1, records1.size()); assertEquals(IP_PREFIX + (i + 1), records1.get(0).getContent()); } @@ -313,7 +313,7 @@ public class CfClientTest { // Use first 2 records for PATCH List patchRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordList(zone, sldNames.get(i), RecordType.A); + List records = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); RecordEntity record = records.get(0); record.setContent(UPDATED_IP_PREFIX + (i + 1)); patchRecords.add(record); @@ -323,7 +323,7 @@ public class CfClientTest { // Verify both records were updated for (int i = 0; i < 2; i++) { - List updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A); + List updatedRecords = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); assertEquals(1, updatedRecords.size()); assertEquals(UPDATED_IP_PREFIX + (i + 1), updatedRecords.get(0).getContent()); } @@ -333,7 +333,7 @@ public class CfClientTest { // Delete first 2 records List deleteRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordList(zone, sldNames.get(i), RecordType.A); + List records = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); deleteRecords.add(records.get(0)); } @@ -343,7 +343,7 @@ public class CfClientTest { for (int i = 0; i < 2; i++) { String sldName = sldNames.get(i); assertThrows(CloudflareNotFoundException.class, - () -> client.recordList(zone, sldName, RecordType.A)); + () -> client.recordListBySubdomain(zone, sldName, RecordType.A)); } } @@ -359,7 +359,7 @@ public class CfClientTest { // Now use PUT to replace them List putRecords = new ArrayList<>(); for (int i = 0; i < 2; i++) { - List records = client.recordList(zone, sldNames.get(i), RecordType.A); + List records = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); RecordEntity record = records.get(0); record.setContent(UPDATED_IP_PREFIX + (i + 1)); putRecords.add(record); @@ -368,7 +368,7 @@ public class CfClientTest { // Verify both records were updated for (int i = 0; i < 2; i++) { - List updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A); + List updatedRecords = client.recordListBySubdomain(zone, sldNames.get(i), RecordType.A); assertEquals(1, updatedRecords.size()); assertEquals(UPDATED_IP_PREFIX + (i + 1), updatedRecords.get(0).getContent()); } @@ -376,7 +376,7 @@ public class CfClientTest { private void assertValidBatchedRecord(RecordEntity batchedRecord, RecordEntity originalRecord) { assertNotNull(batchedRecord.getId()); - assertEquals(originalRecord.getSld(), batchedRecord.getSld()); + assertEquals(originalRecord.getSubdomain(), batchedRecord.getSubdomain()); assertEquals(originalRecord.getType(), batchedRecord.getType()); assertNotNull(batchedRecord.getCreatedOn()); } @@ -393,7 +393,7 @@ public class CfClientTest { .create(RecordType.A, "192.168.100.1", TTL); assertNotNull(created.getId()); - assertEquals(fluentSld, created.getSld()); + assertEquals(fluentSld, created.getSubdomain()); assertEquals("192.168.100.1", created.getContent()); // Test fluent get diff --git a/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java b/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java index bc5b7f9..6254ab3 100644 --- a/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java +++ b/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java @@ -5,6 +5,7 @@ import codes.thischwa.cf.model.*; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; @@ -218,7 +219,7 @@ class CfDnsClientMockTest { CfDnsClient spyClient = spy(client); doReturn(mockResponse).when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); - List records = spyClient.recordList(zone, "test"); + List records = spyClient.recordListBySubdomain(zone, "test"); assertNotNull(records); assertEquals(1, records.size()); @@ -239,7 +240,7 @@ class CfDnsClientMockTest { CfDnsClient spyClient = spy(client); doReturn(mockResponse).when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); - List records = spyClient.recordList(zone, "test", RecordType.A); + List records = spyClient.recordListBySubdomain(zone, "test", RecordType.A); assertNotNull(records); assertEquals(1, records.size()); @@ -260,7 +261,7 @@ class CfDnsClientMockTest { CfDnsClient spyClient = spy(client); doReturn(mockResponse).when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); - List records = spyClient.recordList(zone, RecordType.A); + List records = spyClient.recordListByType(zone, RecordType.A); assertNotNull(records); assertEquals(1, records.size()); @@ -360,7 +361,7 @@ class CfDnsClientMockTest { ZoneEntity zone = createTestZone(); CfDnsClient spyClient = spy(client); - doThrow(new CloudflareNotFoundException("Not found")).when(spyClient).recordList(any(), anyString(), any()); + doThrow(new CloudflareNotFoundException("Not found")).when(spyClient).recordListBySubdomain(any(), anyString(), any()); // Should not throw exception when record doesn't exist assertDoesNotThrow(() -> spyClient.recordDeleteTypeIfExists(zone, "test", RecordType.A)); @@ -396,4 +397,338 @@ class CfDnsClientMockTest { assertEquals(1, result.getPosts().size()); assertEquals(TEST_ZONE_ID, result.getPosts().get(0).getZoneId()); } + + private ZoneMultipleResponse zoneResponse(List zones, ResultInfo resultInfo) { + ZoneMultipleResponse resp = new ZoneMultipleResponse(); + resp.setResult(zones); + resp.setResultInfo(resultInfo); + resp.setResponseResultInfo(createSuccessResultInfo()); + return resp; + } + + private RecordMultipleResponse recordResponse(List records, ResultInfo resultInfo) { + RecordMultipleResponse resp = new RecordMultipleResponse(); + resp.setResult(records); + resp.setResultInfo(resultInfo); + resp.setResponseResultInfo(createSuccessResultInfo()); + return resp; + } + + private static ZoneEntity zone(String id, String name) { + ZoneEntity zone = new ZoneEntity(); + zone.setId(id); + zone.setName(name); + return zone; + } + + @Test + void testZoneGet_NotFound_ReturnsNull() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(zoneResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + + assertNull(spyClient.zoneGet("unknown.com")); + } + + @Test + void testZoneGet_NotFound_ThrowsIfEnabled() throws Exception { + CfDnsClient throwingClient = spy(new CfDnsClientBuilder() + .withApiTokenAuth("test-token") + .withEmptyResultThrowsException(true) + .build()); + doReturn(zoneResponse(List.of(), new ResultInfo(0))) + .when(throwingClient).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + + assertThrows(CloudflareNotFoundException.class, () -> throwingClient.zoneGet("unknown.com")); + } + + @Test + void testZone_NotFound_Throws() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(zoneResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + + assertThrows(CloudflareNotFoundException.class, () -> spyClient.zone("unknown.com")); + } + + @Test + void testZoneList_FetchesAllPages() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(zoneResponse(List.of(zone("z1", "a.com"), zone("z2", "b.com")), + new ResultInfo(1, 2, 2, 2, 3))) + .when(spyClient).getRequest(eq("/zones?page=1&per_page=" + CfDnsClient.ZONES_PER_PAGE), + eq(ZoneMultipleResponse.class)); + doReturn(zoneResponse(List.of(zone("z3", "c.com")), new ResultInfo(2, 2, 2, 1, 3))) + .when(spyClient).getRequest(eq("/zones?page=2&per_page=" + CfDnsClient.ZONES_PER_PAGE), + eq(ZoneMultipleResponse.class)); + + List zones = spyClient.zoneList(); + + assertEquals(List.of("a.com", "b.com", "c.com"), zones.stream().map(ZoneEntity::getName).toList()); + verify(spyClient, times(2)).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + } + + @Test + void testRecordListByType_FetchesAllPages() throws Exception { + ZoneEntity zone = createTestZone(); + String base = "/zones/" + TEST_ZONE_ID + "/dns_records?type=A&page=%d&per_page=" + CfDnsClient.RECORDS_PER_PAGE; + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(RecordEntity.build("a.example.com", RecordType.A, 60, "1.1.1.1")), + new ResultInfo(1, 1, 2, 1, 2))) + .when(spyClient).getRequest(eq(String.format(base, 1)), eq(RecordMultipleResponse.class)); + doReturn(recordResponse(List.of(RecordEntity.build("b.example.com", RecordType.A, 60, "2.2.2.2")), + new ResultInfo(2, 1, 2, 1, 2))) + .when(spyClient).getRequest(eq(String.format(base, 2)), eq(RecordMultipleResponse.class)); + + List records = spyClient.recordListByType(zone, RecordType.A); + + assertEquals(2, records.size()); + assertEquals("b.example.com", records.get(1).getName()); + } + + @Test + void testRecordListBySld_FetchesAllPages() throws Exception { + ZoneEntity zone = createTestZone(); + String base = "/zones/" + TEST_ZONE_ID + "/dns_records?name=test.example.com&page=%d&per_page=" + + CfDnsClient.RECORDS_PER_PAGE; + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(RecordEntity.build("test.example.com", RecordType.A, 60, "1.1.1.1")), + new ResultInfo(1, 1, 2, 1, 2))) + .when(spyClient).getRequest(eq(String.format(base, 1)), eq(RecordMultipleResponse.class)); + doReturn(recordResponse(List.of(RecordEntity.build("test.example.com", RecordType.AAAA, 60, "::1")), + new ResultInfo(2, 1, 2, 1, 2))) + .when(spyClient).getRequest(eq(String.format(base, 2)), eq(RecordMultipleResponse.class)); + + assertEquals(2, spyClient.recordListBySubdomain(zone, "test").size()); + } + + @Test + void testRecordList_SetsZoneNameForSld() throws Exception { + ZoneEntity zone = createTestZone(); + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of( + RecordEntity.build("example.com", RecordType.A, 60, "1.1.1.1"), + RecordEntity.build("my.sub.example.com", RecordType.A, 60, "2.2.2.2")), + new ResultInfo(2))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + List records = spyClient.recordList(zone); + + assertEquals(TEST_ZONE_NAME, records.get(0).getZoneName()); + assertEquals("@", records.get(0).getSubdomain()); + assertEquals("my.sub", records.get(1).getSubdomain()); + } + + @Test + void testRecordListByApex() throws Exception { + ZoneEntity zone = createTestZone(); + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + spyClient.recordListBySubdomain(zone, CfDnsClient.APEX); + + verify(spyClient).getRequest( + eq("/zones/" + TEST_ZONE_ID + "/dns_records?name=example.com&page=1&per_page=" + + CfDnsClient.RECORDS_PER_PAGE), + eq(RecordMultipleResponse.class)); + } + + @Test + void testRecordDelete_NoResult_ReturnsFalse() throws Exception { + RecordSingleResponse mockResponse = new RecordSingleResponse(); + mockResponse.setResponseResultInfo(createSuccessResultInfo()); + CfDnsClient spyClient = spy(client); + doReturn(mockResponse).when(spyClient).deleteRequest(anyString(), eq(RecordSingleResponse.class)); + + assertFalse(spyClient.recordDelete(createTestZone(), TEST_RECORD_ID)); + } + + @Test + void testRecordDelete_OtherId_ReturnsFalse() throws Exception { + RecordSingleResponse mockResponse = new RecordSingleResponse(); + RecordEntity other = new RecordEntity(); + other.setId("other"); + mockResponse.setResult(other); + mockResponse.setResponseResultInfo(createSuccessResultInfo()); + CfDnsClient spyClient = spy(client); + doReturn(mockResponse).when(spyClient).deleteRequest(anyString(), eq(RecordSingleResponse.class)); + + assertFalse(spyClient.recordDelete(createTestZone(), TEST_RECORD_ID)); + } + + @Test + void testRecordBatch_UsesFullRecordName() throws Exception { + ZoneEntity zone = createTestZone(); + RecordEntity apex = RecordEntity.build("example.com", RecordType.A, 300, "1.2.3.4"); + RecordEntity multiLevel = RecordEntity.build("a.b.example.com", RecordType.A, 300, "1.2.3.5"); + + BatchResponse mockResponse = createBatchResponse(); + mockResponse.setResult(new BatchEntry()); + mockResponse.setResponseResultInfo(createSuccessResultInfo()); + CfDnsClient spyClient = spy(client); + doReturn(mockResponse).when(spyClient).postRequest(anyString(), any(), eq(BatchResponse.class)); + + spyClient.recordBatch(zone, List.of(apex, multiLevel), List.of(multiLevel), null, List.of(apex)); + + ArgumentCaptor payload = ArgumentCaptor.forClass(Object.class); + verify(spyClient).postRequest(anyString(), payload.capture(), eq(BatchResponse.class)); + BatchEntry sent = (BatchEntry) payload.getValue(); + assertEquals(List.of("example.com", "a.b.example.com"), + sent.getPosts().stream().map(RecordEntity::getName).toList()); + assertEquals("a.b.example.com", sent.getPuts().get(0).getName()); + // deletes only need the ID + assertNull(sent.getDeletes().get(0).getName()); + } + + @Test + void testRecordList_NullPagingIsUnambiguousAndFetchesAll() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(RecordEntity.build("a.example.com", RecordType.A, 60, "1.1.1.1")), + new ResultInfo(1))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + assertEquals(1, spyClient.recordList(createTestZone(), null).size()); + } + + @Test + void testRecordListByType_SingleTypeIsFilteredServerSide() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + spyClient.recordListByType(createTestZone(), RecordType.MX); + spyClient.recordListBySubdomain(createTestZone(), "www", RecordType.TXT); + + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + "/dns_records?type=MX&page=1&per_page=" + + CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class)); + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?name=www.example.com&type=TXT&page=1&per_page=" + + CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class)); + } + + @Test + void testRecordListByType_MultipleTypesAreFilteredClientSide() throws Exception { + RecordEntity unknownType = new RecordEntity(); + unknownType.setName("x.example.com"); + unknownType.setType("UNKNOWN_FUTURE_TYPE"); + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of( + RecordEntity.build("a.example.com", RecordType.A, 60, "1.1.1.1"), + RecordEntity.build("a.example.com", RecordType.AAAA, 60, "::1"), + RecordEntity.build("a.example.com", RecordType.TXT, 60, "txt"), + unknownType), new ResultInfo(4))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + // an unknown record type in the response must not break the filter + List records = spyClient.recordListByType(createTestZone(), RecordType.A, RecordType.AAAA); + + assertEquals(List.of("A", "AAAA"), records.stream().map(RecordEntity::getType).toList()); + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + "/dns_records?page=1&per_page=" + + CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class)); + } + + private static RecordEntity fetchedMxRecord() { + RecordEntity rec = RecordEntity.build("example.com", RecordType.MX, 300, "mail.example.com"); + rec.setId(TEST_RECORD_ID); + rec.setPriority(10); + rec.setProxied(false); + rec.setComment("primary mx"); + rec.setTags(List.of("env:prod")); + rec.setZoneId(TEST_ZONE_ID); + rec.setZoneName(TEST_ZONE_NAME); + rec.setLocked(false); + rec.setProxiable(false); + rec.setCreatedOn(java.time.Instant.parse("2025-01-01T00:00:00Z")); + rec.setModifiedOn(java.time.Instant.parse("2025-01-02T00:00:00Z")); + return rec; + } + + private static void assertOnlyWritableFields(RecordEntity sent) { + assertEquals("example.com", sent.getName()); + assertEquals("MX", sent.getType()); + assertEquals("mail.example.com", sent.getContent()); + assertEquals(10, sent.getPriority()); + assertEquals(false, sent.getProxied()); + assertEquals("primary mx", sent.getComment()); + assertEquals(List.of("env:prod"), sent.getTags()); + assertNull(sent.getZoneId()); + assertNull(sent.getZoneName()); + assertNull(sent.getLocked()); + assertNull(sent.getProxiable()); + assertNull(sent.getCreatedOn()); + assertNull(sent.getModifiedOn()); + } + + private RecordSingleResponse singleResponse(RecordEntity rec) { + RecordSingleResponse resp = new RecordSingleResponse(); + resp.setResult(rec); + resp.setResponseResultInfo(createSuccessResultInfo()); + return resp; + } + + @Test + void testRecordUpdate_DoesNotModifyGivenRecordAndSendsWritableFields() throws Exception { + RecordEntity rec = fetchedMxRecord(); + RecordEntity before = fetchedMxRecord(); + CfDnsClient spyClient = spy(client); + doReturn(singleResponse(fetchedMxRecord())) + .when(spyClient).patchRequest(anyString(), any(), eq(RecordSingleResponse.class)); + + spyClient.recordUpdate(createTestZone(), rec); + + assertEquals(before, rec); + ArgumentCaptor payload = ArgumentCaptor.forClass(Object.class); + verify(spyClient).patchRequest(eq("/zones/" + TEST_ZONE_ID + "/dns_records/" + TEST_RECORD_ID), + payload.capture(), eq(RecordSingleResponse.class)); + assertOnlyWritableFields((RecordEntity) payload.getValue()); + } + + @Test + void testRecordCreate_SendsWritableFieldsWithoutId() throws Exception { + RecordEntity rec = fetchedMxRecord(); + CfDnsClient spyClient = spy(client); + doReturn(singleResponse(fetchedMxRecord())) + .when(spyClient).postRequest(anyString(), any(), eq(RecordSingleResponse.class)); + + spyClient.recordCreate(createTestZone(), rec); + + ArgumentCaptor payload = ArgumentCaptor.forClass(Object.class); + verify(spyClient).postRequest(anyString(), payload.capture(), eq(RecordSingleResponse.class)); + RecordEntity sent = (RecordEntity) payload.getValue(); + assertOnlyWritableFields(sent); + assertNull(sent.getId()); + assertEquals(TEST_RECORD_ID, rec.getId()); + } + + @Test + void testRecordBatch_KeepsPriorityDataAndProxied() throws Exception { + RecordEntity srv = RecordEntity.build("_sip._tcp.example.com", RecordType.SRV, 300, null); + srv.setId("srv1"); + srv.setPriority(10); + srv.setData(Map.of("weight", 5, "port", 5060, "target", "sip.example.com")); + RecordEntity proxied = RecordEntity.build("www.example.com", RecordType.A, 1, "1.2.3.4"); + proxied.setId("www1"); + proxied.setProxied(true); + + BatchResponse mockResponse = createBatchResponse(); + mockResponse.setResult(new BatchEntry()); + mockResponse.setResponseResultInfo(createSuccessResultInfo()); + CfDnsClient spyClient = spy(client); + doReturn(mockResponse).when(spyClient).postRequest(anyString(), any(), eq(BatchResponse.class)); + + spyClient.recordBatch(createTestZone(), List.of(srv), List.of(proxied), List.of(srv), null); + + ArgumentCaptor payload = ArgumentCaptor.forClass(Object.class); + verify(spyClient).postRequest(anyString(), payload.capture(), eq(BatchResponse.class)); + BatchEntry sent = (BatchEntry) payload.getValue(); + RecordEntity sentPost = sent.getPosts().get(0); + assertNull(sentPost.getId()); + assertEquals(10, sentPost.getPriority()); + assertEquals(5060, sentPost.getData().get("port")); + assertEquals("www1", sent.getPuts().get(0).getId()); + assertEquals(true, sent.getPuts().get(0).getProxied()); + assertEquals("srv1", sent.getPatches().get(0).getId()); + assertEquals(10, sent.getPatches().get(0).getPriority()); + } } diff --git a/src/test/java/codes/thischwa/cf/ObjectMapperTest.java b/src/test/java/codes/thischwa/cf/ObjectMapperTest.java index 529a581..5148830 100644 --- a/src/test/java/codes/thischwa/cf/ObjectMapperTest.java +++ b/src/test/java/codes/thischwa/cf/ObjectMapperTest.java @@ -3,12 +3,15 @@ package codes.thischwa.cf; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; import codes.thischwa.cf.model.AbstractResponse; import codes.thischwa.cf.model.BatchResponse; +import codes.thischwa.cf.model.RecordEntity; import codes.thischwa.cf.model.RecordMultipleResponse; import codes.thischwa.cf.model.RecordSingleResponse; +import codes.thischwa.cf.model.RecordType; import codes.thischwa.cf.model.ResponseResultInfo; import codes.thischwa.cf.model.ZoneMultipleResponse; import java.io.InputStream; @@ -50,4 +53,35 @@ public class ObjectMapperTest { fail("fail for " + clazz + ": " + e.getMessage()); } } + + @Test + void testSubdomainIsNotSerialized() { + RecordEntity rec = RecordEntity.build("www.example.com", RecordType.A, 60, "1.2.3.4"); + rec.setZoneName("example.com"); + String json = mapper.writeValueAsString(rec); + assertTrue(json.contains("\"name\":\"www.example.com\""), json); + assertFalse(json.contains("subdomain"), json); + assertFalse(json.contains("sld"), json); + } + + @Test + void testRecordFieldsAreMappedInSnakeCase() { + String json = """ + {"id":"r1","name":"_sip._tcp.example.com","type":"SRV","ttl":300,"priority":10, + "comment":"sip","tags":["env:prod"], + "data":{"weight":5,"port":5060,"target":"sip.example.com"}, + "created_on":"2025-01-20T08:56:34.736214Z","modified_on":"2025-01-21T08:56:34Z"} + """; + RecordEntity rec = mapper.readValue(json, RecordEntity.class); + assertEquals(10, rec.getPriority()); + assertEquals("sip", rec.getComment()); + assertEquals(List.of("env:prod"), rec.getTags()); + assertEquals(5060, rec.getData().get("port")); + assertEquals(java.time.Instant.parse("2025-01-20T08:56:34.736214Z"), rec.getCreatedOn()); + assertEquals(java.time.Instant.parse("2025-01-21T08:56:34Z"), rec.getModifiedOn()); + + String out = mapper.writeValueAsString(rec); + assertTrue(out.contains("\"priority\":10"), out); + assertTrue(out.contains("\"created_on\":\"2025-01-20T08:56:34.736214Z\""), out); + } } diff --git a/src/test/java/codes/thischwa/cf/ResponseValidatorTest.java b/src/test/java/codes/thischwa/cf/ResponseValidatorTest.java index aed5672..e5c358b 100644 --- a/src/test/java/codes/thischwa/cf/ResponseValidatorTest.java +++ b/src/test/java/codes/thischwa/cf/ResponseValidatorTest.java @@ -11,6 +11,8 @@ import codes.thischwa.cf.model.RecordMultipleResponse; import codes.thischwa.cf.model.RecordSingleResponse; import codes.thischwa.cf.model.ResponseResultInfo; import codes.thischwa.cf.model.ResultInfo; +import codes.thischwa.cf.model.ZoneEntity; +import codes.thischwa.cf.model.ZoneMultipleResponse; import java.util.ArrayList; import java.util.List; import org.junit.jupiter.api.BeforeEach; @@ -130,4 +132,44 @@ class ResponseValidatorTest { assertDoesNotThrow(() -> validatorWithException.validate(mockSingleResponse, false)); assertDoesNotThrow(() -> validatorWithoutException.validate(mockSingleResponse, false)); } -} \ No newline at end of file + + private static ZoneMultipleResponse zoneResponse(int count) { + ZoneMultipleResponse resp = new ZoneMultipleResponse(); + ResponseResultInfo info = new ResponseResultInfo(); + info.setSuccess(true); + resp.setResponseResultInfo(info); + List zones = new ArrayList<>(); + for (int i = 0; i < count; i++) { + zones.add(new ZoneEntity()); + } + resp.setResult(zones); + return resp; + } + + @Test + void validateZoneResponseEmptyWithExceptionEnabled() { + ZoneMultipleResponse resp = zoneResponse(0); + resp.setResultInfo(new ResultInfo(0)); + assertThrows(CloudflareNotFoundException.class, () -> validatorWithException.validate(resp, true)); + assertDoesNotThrow(() -> validatorWithoutException.validate(resp, true)); + } + + @Test + void validateZoneResponseMultipleWhenSingleExpected() { + ZoneMultipleResponse resp = zoneResponse(2); + resp.setResultInfo(new ResultInfo(2)); + CloudflareApiException exception = assertThrows(CloudflareApiException.class, + () -> validatorWithoutException.validate(resp, true)); + assertTrue(exception.getMessage().contains("Unexpected result count: 2")); + } + + @Test + void validateMultipleResponseWithoutResultInfoFallsBackToResultSize() { + // no result_info -> count is derived from the result list + assertThrows(CloudflareNotFoundException.class, + () -> validatorWithException.validate(zoneResponse(0), false)); + assertThrows(CloudflareApiException.class, + () -> validatorWithoutException.validate(zoneResponse(2), true)); + assertDoesNotThrow(() -> validatorWithException.validate(zoneResponse(1), true)); + } +} diff --git a/src/test/java/codes/thischwa/cf/fluent/FluentApiTest.java b/src/test/java/codes/thischwa/cf/fluent/FluentApiTest.java index f87c330..fd3bef1 100644 --- a/src/test/java/codes/thischwa/cf/fluent/FluentApiTest.java +++ b/src/test/java/codes/thischwa/cf/fluent/FluentApiTest.java @@ -59,7 +59,7 @@ class FluentApiTest { RecordEntity rec2 = RecordEntity.build("www.example.com", RecordType.A, 300, "1.2.3.5"); List expectedRecords = List.of(rec1, rec2); - when(mockClient.recordList(eq(testZone), any(RecordType[].class))) + when(mockClient.recordListByType(eq(testZone), any(RecordType[].class))) .thenReturn(expectedRecords); ZoneOperations zoneOps = new ZoneOperationsImpl(mockClient, testZone); @@ -67,7 +67,7 @@ class FluentApiTest { assertNotNull(result); assertEquals(2, result.size()); - verify(mockClient, times(1)).recordList(eq(testZone), any(RecordType[].class)); + verify(mockClient, times(1)).recordListByType(eq(testZone), any(RecordType[].class)); } @Test @@ -75,7 +75,7 @@ class FluentApiTest { RecordEntity rec1 = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.4"); List expectedRecords = List.of(rec1); - when(mockClient.recordList(eq(testZone), any(RecordType[].class))) + when(mockClient.recordListByType(eq(testZone), any(RecordType[].class))) .thenReturn(expectedRecords); ZoneOperations zoneOps = new ZoneOperationsImpl(mockClient, testZone); @@ -83,7 +83,7 @@ class FluentApiTest { assertNotNull(result); assertEquals(1, result.size()); - verify(mockClient, times(1)).recordList(eq(testZone), any(RecordType[].class)); + verify(mockClient, times(1)).recordListByType(eq(testZone), any(RecordType[].class)); } @Test @@ -91,7 +91,7 @@ class FluentApiTest { RecordEntity rec1 = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.4"); List expectedRecords = List.of(rec1); - when(mockClient.recordList(eq(testZone), eq(TEST_SLD), any())) + when(mockClient.recordListBySubdomain(eq(testZone), eq(TEST_SLD), any())) .thenReturn(expectedRecords); RecordOperations recordOps = new RecordOperationsImpl(mockClient, testZone, TEST_SLD, null); @@ -100,7 +100,7 @@ class FluentApiTest { assertNotNull(result); assertEquals(1, result.size()); assertEquals("1.2.3.4", result.get(0).getContent()); - verify(mockClient, times(1)).recordList(eq(testZone), eq(TEST_SLD), any()); + verify(mockClient, times(1)).recordListBySubdomain(eq(testZone), eq(TEST_SLD), any()); } @Test @@ -109,7 +109,7 @@ class FluentApiTest { List expectedRecords = List.of(rec1); RecordType[] types = {RecordType.A}; - when(mockClient.recordList(eq(testZone), eq(TEST_SLD), eq(types))) + when(mockClient.recordListBySubdomain(eq(testZone), eq(TEST_SLD), eq(types))) .thenReturn(expectedRecords); RecordOperations recordOps = new RecordOperationsImpl(mockClient, testZone, TEST_SLD, types); @@ -117,7 +117,7 @@ class FluentApiTest { assertNotNull(result); assertEquals(1, result.size()); - verify(mockClient, times(1)).recordList(eq(testZone), eq(TEST_SLD), eq(types)); + verify(mockClient, times(1)).recordListBySubdomain(eq(testZone), eq(TEST_SLD), eq(types)); } @Test @@ -125,7 +125,7 @@ class FluentApiTest { RecordEntity createdRecord = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.4"); createdRecord.setId(TEST_RECORD_ID); - when(mockClient.recordCreateSld(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4"))) + when(mockClient.recordCreateSubdomain(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4"))) .thenReturn(createdRecord); RecordOperations recordOps = new RecordOperationsImpl(mockClient, testZone, TEST_SLD, null); @@ -134,7 +134,7 @@ class FluentApiTest { assertNotNull(result); assertEquals(TEST_RECORD_ID, result.getId()); assertEquals("1.2.3.4", result.getContent()); - verify(mockClient, times(1)).recordCreateSld(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4")); + verify(mockClient, times(1)).recordCreateSubdomain(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4")); } @Test @@ -145,7 +145,7 @@ class FluentApiTest { RecordEntity updatedRecord = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.5"); updatedRecord.setId(TEST_RECORD_ID); - when(mockClient.recordList(eq(testZone), eq(TEST_SLD), any())) + when(mockClient.recordListBySubdomain(eq(testZone), eq(TEST_SLD), any())) .thenReturn(List.of(existingRecord)); when(mockClient.recordUpdate(eq(testZone), any(RecordEntity.class))) .thenReturn(updatedRecord); @@ -155,13 +155,17 @@ class FluentApiTest { assertNotNull(result); assertEquals("1.2.3.5", result.getContent()); - verify(mockClient, times(1)).recordList(eq(testZone), eq(TEST_SLD), any()); - verify(mockClient, times(1)).recordUpdate(eq(testZone), any(RecordEntity.class)); + verify(mockClient, times(1)).recordListBySubdomain(eq(testZone), eq(TEST_SLD), any()); + // only ID and new content are sent (partial update) + verify(mockClient, times(1)).recordUpdate(eq(testZone), argThat(rec -> + TEST_RECORD_ID.equals(rec.getId()) && "1.2.3.5".equals(rec.getContent()) + && rec.getName() == null && rec.getTtl() == null)); + assertEquals("1.2.3.4", existingRecord.getContent()); } @Test void testRecordOperations_Update_NoRecordsFound() throws CloudflareApiException { - when(mockClient.recordList(eq(testZone), eq(TEST_SLD), any())) + when(mockClient.recordListBySubdomain(eq(testZone), eq(TEST_SLD), any())) .thenReturn(List.of()); RecordOperations recordOps = new RecordOperationsImpl(mockClient, testZone, TEST_SLD, null); @@ -171,7 +175,7 @@ class FluentApiTest { }); assertTrue(exception.getMessage().contains("No recs found")); - verify(mockClient, times(1)).recordList(eq(testZone), eq(TEST_SLD), any()); + verify(mockClient, times(1)).recordListBySubdomain(eq(testZone), eq(TEST_SLD), any()); verify(mockClient, never()).recordUpdate(any(), any()); } @@ -180,7 +184,7 @@ class FluentApiTest { RecordEntity rec1 = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.4"); RecordEntity rec2 = RecordEntity.build("test.example.com", RecordType.AAAA, 300, "::1"); - when(mockClient.recordList(eq(testZone), eq(TEST_SLD), any())) + when(mockClient.recordListBySubdomain(eq(testZone), eq(TEST_SLD), any())) .thenReturn(List.of(rec1, rec2)); RecordOperations recordOps = new RecordOperationsImpl(mockClient, testZone, TEST_SLD, null); @@ -190,7 +194,7 @@ class FluentApiTest { }); assertTrue(exception.getMessage().contains("Multiple recs found")); - verify(mockClient, times(1)).recordList(eq(testZone), eq(TEST_SLD), any()); + verify(mockClient, times(1)).recordListBySubdomain(eq(testZone), eq(TEST_SLD), any()); verify(mockClient, never()).recordUpdate(any(), any()); } @@ -220,7 +224,7 @@ class FluentApiTest { RecordEntity createdRecord = RecordEntity.build("test.example.com", RecordType.A, 300, "1.2.3.4"); createdRecord.setId(TEST_RECORD_ID); - when(mockClient.recordCreateSld(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4"))) + when(mockClient.recordCreateSubdomain(eq(testZone), eq(TEST_SLD), eq(300), eq(RecordType.A), eq("1.2.3.4"))) .thenReturn(createdRecord); ZoneOperations zoneOps = new ZoneOperationsImpl(mockClient, testZone); diff --git a/src/test/java/codes/thischwa/cf/model/RecordEntityTest.java b/src/test/java/codes/thischwa/cf/model/RecordEntityTest.java index 4509b7d..1e02d1e 100644 --- a/src/test/java/codes/thischwa/cf/model/RecordEntityTest.java +++ b/src/test/java/codes/thischwa/cf/model/RecordEntityTest.java @@ -41,19 +41,19 @@ public class RecordEntityTest { @Test void testGetSld() { RecordEntity rec = new RecordEntity(); - assertNull(rec.getSld()); + assertNull(rec.getSubdomain()); rec.setName("sub.example.com"); - assertEquals("sub", rec.getSld()); + assertEquals("sub", rec.getSubdomain()); rec.setName("example.com"); - assertEquals("example", rec.getSld()); + assertEquals("example", rec.getSubdomain()); rec.setName("host"); - assertEquals("host", rec.getSld()); + assertEquals("host", rec.getSubdomain()); rec.setName(".dotstart"); - assertEquals(".dotstart", rec.getSld()); + assertEquals(".dotstart", rec.getSubdomain()); } @Test @@ -61,10 +61,47 @@ public class RecordEntityTest { RecordEntity rec = new RecordEntity(); rec.setName("sub.example.com"); rec.setZoneName("example.com"); - assertEquals("sub", rec.getSld()); + assertEquals("sub", rec.getSubdomain()); rec.setName("my.sub.example.com"); rec.setZoneName("example.com"); - assertEquals("my.sub", rec.getSld()); + assertEquals("my.sub", rec.getSubdomain()); + } + + @Test + void testGetSldApexWithZoneName() { + RecordEntity rec = new RecordEntity(); + rec.setName("example.com"); + rec.setZoneName("example.com"); + assertEquals("@", rec.getSubdomain()); + + rec.setName("Example.COM"); + assertEquals("@", rec.getSubdomain()); + } + + @Test + void testGetSldZoneNameIsNoLabelSuffix() { + // "notexample.com" ends with "example.com", but is not part of the zone + RecordEntity rec = new RecordEntity(); + rec.setName("notexample.com"); + rec.setZoneName("example.com"); + assertEquals("notexample", rec.getSubdomain()); + } + + @Test + void testGetSldCaseInsensitive() { + RecordEntity rec = new RecordEntity(); + rec.setName("WWW.Example.com"); + rec.setZoneName("example.com"); + assertEquals("WWW", rec.getSubdomain()); + } + + @Test + @SuppressWarnings("removal") + void testDeprecatedGetSldDelegatesToGetSubdomain() { + RecordEntity rec = new RecordEntity(); + rec.setName("my.sub.example.com"); + rec.setZoneName("example.com"); + assertEquals(rec.getSubdomain(), rec.getSld()); } } diff --git a/src/test/java/codes/thischwa/cf/model/ZoneEntityTest.java b/src/test/java/codes/thischwa/cf/model/ZoneEntityTest.java index 08d1abc..2af5d32 100644 --- a/src/test/java/codes/thischwa/cf/model/ZoneEntityTest.java +++ b/src/test/java/codes/thischwa/cf/model/ZoneEntityTest.java @@ -3,7 +3,7 @@ package codes.thischwa.cf.model; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; -import java.time.LocalDateTime; +import java.time.Instant; import java.util.Set; import org.junit.jupiter.api.Test; @@ -18,7 +18,7 @@ public class ZoneEntityTest { Set ns = Set.of("ns1.cloudflare.com", "ns2.cloudflare.com"); zone.setNameServers(ns); zone.setOriginalNameServers(ns); - LocalDateTime now = LocalDateTime.now(); + Instant now = Instant.now(); zone.setCreatedOn(now); zone.setModifiedOn(now); zone.setActivatedOn(now);