From 8515f8162138e38c401d08b79da7cc24a6e6a37d Mon Sep 17 00:00:00 2001 From: Thilo Schwarz Date: Fri, 6 Nov 2026 14:28:06 +0100 Subject: [PATCH] ai review (#1) Co-authored-by: gitea-actions-bot Reviewed-on: https://git.mein-gateway.de/thischwa/CloudflareDNS-java/pulls/1 Co-authored-by: Thilo Schwarz --- .gitea/workflows/build-and-analyse.yml | 5 +- .gitignore | 1 + README.md | 140 +++-- changelog.md | 33 +- reports/test.md | 29 +- .../codes/thischwa/cf/CfBasicHttpClient.java | 159 ++++-- .../java/codes/thischwa/cf/CfDnsClient.java | 509 +++++++++++++----- .../codes/thischwa/cf/CfDnsClientBuilder.java | 121 ++++- .../java/codes/thischwa/cf/CfRequest.java | 66 ++- .../thischwa/cf/CloudflareApiException.java | 59 +- .../cf/CloudflareNotFoundException.java | 23 +- .../codes/thischwa/cf/ResponseValidator.java | 21 +- .../thischwa/cf/fluent/RecordOperations.java | 9 +- .../cf/fluent/RecordOperationsImpl.java | 27 +- .../thischwa/cf/fluent/ZoneOperations.java | 17 +- .../cf/fluent/ZoneOperationsImpl.java | 10 +- .../thischwa/cf/model/PagingRequest.java | 69 ++- .../codes/thischwa/cf/model/RecordEntity.java | 84 ++- .../codes/thischwa/cf/model/ZoneEntity.java | 10 +- .../cf/CfBasicHttpClientErrorTest.java | 171 ++++++ .../thischwa/cf/CfBasicHttpClientTest.java | 10 +- .../codes/thischwa/cf/CfClientPenTest.java | 4 +- .../java/codes/thischwa/cf/CfClientTest.java | 314 +++++++++-- .../thischwa/cf/CfDnsClientBuilderTest.java | 54 ++ .../thischwa/cf/CfDnsClientMockTest.java | 480 ++++++++++++++++- .../java/codes/thischwa/cf/CfRequestTest.java | 28 + .../codes/thischwa/cf/ObjectMapperTest.java | 34 ++ .../thischwa/cf/ResponseValidatorTest.java | 44 +- .../thischwa/cf/fluent/FluentApiTest.java | 40 +- .../thischwa/cf/model/PagingRequestTest.java | 21 +- .../thischwa/cf/model/RecordEntityTest.java | 51 +- .../thischwa/cf/model/ZoneEntityTest.java | 4 +- 32 files changed, 2223 insertions(+), 424 deletions(-) create mode 100644 src/test/java/codes/thischwa/cf/CfBasicHttpClientErrorTest.java diff --git a/.gitea/workflows/build-and-analyse.yml b/.gitea/workflows/build-and-analyse.yml index e259b21..da28725 100644 --- a/.gitea/workflows/build-and-analyse.yml +++ b/.gitea/workflows/build-and-analyse.yml @@ -4,7 +4,7 @@ on: push: branches: - develop - - feature* + - 'feature/**' pull_request: types: [ opened, synchronize, reopened ] @@ -25,6 +25,9 @@ jobs: uses: ./.gitea/actions/setup-java-maven - name: Build and test + env: + # required by the live tests (CfClientTest, CfClientPenTest), they are skipped if not set + API_TOKEN: ${{ secrets.API_TOKEN }} run: mvn -B verify - name: Publish Test Report diff --git a/.gitignore b/.gitignore index c22eb4b..8c8fb71 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ cf.yml /docs/apidocs/javadoc.sh /.claude/settings.local.json +/.junie/ diff --git a/README.md b/README.md index a919705..0c9a1a3 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,28 @@ CfDnsClient cfDnsClient = new CfDnsClientBuilder() .build(); ``` +#### Further options: +```java +CfDnsClient cfDnsClient = new CfDnsClientBuilder() + .withApiTokenAuth("your-api-token") + .withBaseUrl("https://custom-api.example.com/client/v4") // must use HTTPS + .withConnectTimeout(Duration.ofSeconds(5)) // default: 10 s + .withResponseTimeout(Duration.ofSeconds(15)) // default: 30 s + .withEmptyResultThrowsException(true) // default: false + .build(); +``` + +`build()` throws an `IllegalStateException` if no authentication is configured. + +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. @@ -73,12 +95,17 @@ List zones = cfDnsClient.zoneList(); zones.forEach(zone -> System.out.println("Zone: " + zone.getName())); ``` -By default, up to 1000 zones are fetched in a single request. Use a `PagingRequest` to control paging: +Without a `PagingRequest`, `zoneList()` fetches zones in pages of 50, requesting further pages as needed. +Use a `PagingRequest` to retrieve a specific page: ```java List zones = cfDnsClient.zoneList(PagingRequest.of(1, 50)); // page 1, 50 zones per page ``` +Page numbers start at 1. Cloudflare accepts page sizes from 5 to 50 for zones and from 1 to 5,000,000 +for DNS records. `PagingRequest.defaultPaging()` requests page 1 with 50 items; it does not fetch +additional pages. + --- ### `zoneGet` @@ -100,49 +127,54 @@ 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 using up to 5,000,000 records per page and combined into one result. +This large page size can consume substantial memory. If paging remains inconsistent after three attempts, the client logs a warning and may return an incomplete list. Use a smaller `PagingRequest` to retrieve one page at a time; further pages must be requested explicitly. +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 +186,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 +210,27 @@ 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), the priority is part of the data +RecordEntity srv = RecordEntity.build("_sip._tcp.example.com", RecordType.SRV, 3600, null); +srv.setData(Map.of("priority", 10, "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 +271,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 @@ -231,6 +279,8 @@ cfDnsClient.recordDeleteTypeIfExists(zone, "api", RecordType.A, RecordType.AAAA) System.out.println("Deletion attempt completed."); ``` +If no record types are specified, records of all types for the subdomain are selected. Each record deletion is attempted independently: a `CloudflareApiException` from one deletion is logged and later records are still processed. No per-record result is returned, so a normal return does not guarantee that every selected record was deleted. Errors while retrieving the records are still reported; no matching records are treated as a no-op. + ### Batch Operations Process multiple DNS record operations (POST, PUT, PATCH, DELETE) in a single batch request. @@ -266,8 +316,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 +334,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 +355,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 +375,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 @@ -383,6 +433,8 @@ client.zone("example.com") .delete(RecordType.A, RecordType.AAAA); ``` +The types passed to `delete` determine which record types are selected; a type filter passed to `getRecord` does not restrict deletion. Calling `delete()` without type arguments selects all record types for that subdomain. A `CloudflareApiException` from an individual deletion is logged and does not stop later attempts; no per-record result is returned. + ### Advantages of Fluent API - **More Readable**: The chain of method calls reads like natural language @@ -425,7 +477,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 +495,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..b3d8505 100644 --- a/changelog.md +++ b/changelog.md @@ -1,10 +1,39 @@ # 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 + - `CfDnsClient#recordCreateSld(...)` was removed; use `recordCreateSubdomain(...)` + - `PagingRequest.defaultPaging()` now requests 50 items instead of 1,000. Page numbers and page sizes are validated; zone requests accept 5–50 items per page, while DNS record requests accept 1–5,000,000. + - `withBaseUrl` only accepts HTTPS URLs (plain HTTP only for loopback hosts like `localhost`), otherwise an `IllegalArgumentException` is thrown + - `build()` throws an `IllegalStateException` if no authentication was configured, `null` credentials throw an `IllegalArgumentException` + - zone names and subdomains with whitespace, control characters or `\ ? # & ; | < > " ' `` ` `` are rejected with an `IllegalArgumentException`, zone and record IDs must be alphanumeric + - 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) + - security: query values (zone names, subdomains) are URL-encoded and IDs are validated, which prevents query parameter injection and path traversal + - connect and response timeouts (defaults: 10 s / 30 s), configurable via `withConnectTimeout` / `withResponseTimeout` + - `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, URI), `data` (e.g. SRV incl. its priority, 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") + - fixed "getRecord" wording in log and exception messages (e.g. "Invalid record type") + - **Deprecation**: the misleading term "sld" was renamed to "subdomain": `RecordEntity#getSld()` is deprecated for removal; use `RecordEntity#getSubdomain()` + - `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; `recordList(zone, null)` uses the maximum DNS page size of 5,000,000 + - fixed: DNS records are listed with a stable order (`order=name`), because without it Cloudflare's pages can overlap and miss records; fetched records are de-duplicated and inconsistent pages are fetched again + - 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/reports/test.md b/reports/test.md index b253bcc..b34aa6b 100644 --- a/reports/test.md +++ b/reports/test.md @@ -1,6 +1,6 @@ # Test Report -_Generated on 2026-10-31 11:26:47 UTC_ +_Generated on 2026-11-06 12:40:48 UTC_ **✅ All tests passed** @@ -8,24 +8,25 @@ _Generated on 2026-10-31 11:26:47 UTC_ | | Tests | Passed | Failed | Skipped | |---|---|---|---|---| -| **Total** | 105 | 90 | 0 | 15 | +| **Total** | 162 | 162 | 0 | 0 | ### Details | Status | Suite | Tests | Passed | Failed | Skipped | |---|---|---|---|---|---| +| ✅ | codes.thischwa.cf.CfBasicHttpClientErrorTest | 7 | 7 | 0 | 0 | | ✅ | codes.thischwa.cf.CfBasicHttpClientTest | 9 | 9 | 0 | 0 | -| ✅ | codes.thischwa.cf.CfClientPenTest | 4 | 0 | 0 | 4 | -| ✅ | codes.thischwa.cf.CfClientTest | 11 | 0 | 0 | 11 | -| ✅ | codes.thischwa.cf.CfDnsClientBuilderTest | 16 | 16 | 0 | 0 | -| ✅ | codes.thischwa.cf.CfDnsClientMockTest | 16 | 16 | 0 | 0 | -| ✅ | codes.thischwa.cf.CfRequestTest | 8 | 8 | 0 | 0 | -| ✅ | codes.thischwa.cf.ObjectMapperTest | 2 | 2 | 0 | 0 | -| ✅ | codes.thischwa.cf.ResponseValidatorTest | 8 | 8 | 0 | 0 | +| ✅ | codes.thischwa.cf.CfClientPenTest | 4 | 4 | 0 | 0 | +| ✅ | codes.thischwa.cf.CfClientTest | 18 | 18 | 0 | 0 | +| ✅ | codes.thischwa.cf.CfDnsClientBuilderTest | 21 | 21 | 0 | 0 | +| ✅ | codes.thischwa.cf.CfDnsClientMockTest | 41 | 41 | 0 | 0 | +| ✅ | codes.thischwa.cf.CfRequestTest | 10 | 10 | 0 | 0 | +| ✅ | codes.thischwa.cf.ObjectMapperTest | 4 | 4 | 0 | 0 | +| ✅ | codes.thischwa.cf.ResponseValidatorTest | 11 | 11 | 0 | 0 | | ✅ | codes.thischwa.cf.fluent.FluentApiTest | 15 | 15 | 0 | 0 | | ✅ | codes.thischwa.cf.model.BatchEntryTest | 2 | 2 | 0 | 0 | -| ✅ | codes.thischwa.cf.model.PagingRequestTest | 4 | 4 | 0 | 0 | -| ✅ | codes.thischwa.cf.model.RecordEntityTest | 6 | 6 | 0 | 0 | +| ✅ | codes.thischwa.cf.model.PagingRequestTest | 6 | 6 | 0 | 0 | +| ✅ | codes.thischwa.cf.model.RecordEntityTest | 10 | 10 | 0 | 0 | | ✅ | codes.thischwa.cf.model.RecordTypeTest | 3 | 3 | 0 | 0 | | ✅ | codes.thischwa.cf.model.ZoneEntityTest | 1 | 1 | 0 | 0 | @@ -33,6 +34,6 @@ _Generated on 2026-10-31 11:26:47 UTC_ | Package | Line Coverage | Branch Coverage | |---|---|---| -| codes.thischwa.cf.fluent | 100% (25/25) | 100% (4/4) | -| codes.thischwa.cf.model | 100% (93/93) | 90% (9/10) | -| codes.thischwa.cf | 89% (249/279) | 71% (51/72) | +| codes.thischwa.cf.fluent | 100% (23/23) | 100% (4/4) | +| codes.thischwa.cf.model | 100% (107/107) | 95% (19/20) | +| codes.thischwa.cf | 97% (433/447) | 89% (191/214) | diff --git a/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java b/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java index d1b4edb..36c3ec2 100644 --- a/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java +++ b/src/main/java/codes/thischwa/cf/CfBasicHttpClient.java @@ -1,22 +1,32 @@ 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.time.Duration; +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; import org.apache.hc.client5.http.classic.methods.HttpPatch; import org.apache.hc.client5.http.classic.methods.HttpPost; import org.apache.hc.client5.http.classic.methods.HttpPut; +import org.apache.hc.client5.http.config.ConnectionConfig; +import org.apache.hc.client5.http.config.RequestConfig; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; import org.apache.hc.client5.http.impl.classic.HttpClients; +import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder; 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; +import org.apache.hc.core5.util.Timeout; import org.jetbrains.annotations.NotNull; import tools.jackson.core.JacksonException; import tools.jackson.databind.ObjectMapper; @@ -25,13 +35,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) { } @@ -43,65 +57,112 @@ abstract class CfBasicHttpClient { * @param auth the authentication mechanism to use */ CfBasicHttpClient(@NotNull String baseUrl, @NotNull CfDnsClientBuilder.CfAuth auth) { + this(baseUrl, auth, CfDnsClientBuilder.DEFAULT_CONNECT_TIMEOUT, + CfDnsClientBuilder.DEFAULT_RESPONSE_TIMEOUT); + } + + /** + * Creates a new Cloudflare HTTP client with the specified base URL, authentication and timeouts. + * + * @param baseUrl the base URL for the Cloudflare API + * @param auth the authentication mechanism to use + * @param connectTimeout the timeout for establishing a connection + * @param responseTimeout the timeout for waiting for the response data + */ + CfBasicHttpClient(@NotNull String baseUrl, @NotNull CfDnsClientBuilder.CfAuth auth, + @NotNull Duration connectTimeout, @NotNull Duration responseTimeout) { this.baseUrl = baseUrl; this.auth = auth; this.objectMapper = JsonConf.initObjectMapper(); + this.httpClient = createHttpClient(connectTimeout, responseTimeout); } - private CloseableHttpClient createHttpClient() { - return HttpClients.custom().addRequestInterceptorFirst((request, context, execChain) -> { - request.addHeader(HttpHeaders.ACCEPT_CHARSET, "UTF-8"); - request.addHeader(HttpHeaders.ACCEPT_ENCODING, "gzip"); - request.addHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.getMimeType()); - request.addHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.getMimeType()); - if (request instanceof ClassicHttpRequest classicRequest) { - auth.applyAuth(classicRequest); - } - }).build(); + /** + * 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(Duration connectTimeout, Duration responseTimeout) { + Timeout connect = Timeout.ofMilliseconds(connectTimeout.toMillis()); + Timeout response = Timeout.ofMilliseconds(responseTimeout.toMillis()); + ConnectionConfig connectionConfig = ConnectionConfig.custom() + .setConnectTimeout(connect) + .setSocketTimeout(response) + .build(); + RequestConfig requestConfig = RequestConfig.custom() + .setConnectionRequestTimeout(connect) + .setResponseTimeout(response) + .build(); + return HttpClients.custom() + .setConnectionManager(PoolingHttpClientConnectionManagerBuilder.create() + .setDefaultConnectionConfig(connectionConfig) + .build()) + .setDefaultRequestConfig(requestConfig) + .addRequestInterceptorFirst((request, context, execChain) -> { + request.addHeader(HttpHeaders.ACCEPT_CHARSET, "UTF-8"); + request.addHeader(HttpHeaders.ACCEPT_ENCODING, "gzip"); + request.addHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.getMimeType()); + request.addHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.getMimeType()); + if (request instanceof ClassicHttpRequest classicRequest) { + auth.applyAuth(classicRequest); + } + }) + .build(); } 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..da0c926 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,15 +11,20 @@ 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.time.Duration; 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.regex.Pattern; import java.util.stream.Collectors; import lombok.extern.slf4j.Slf4j; import org.jetbrains.annotations.Nullable; @@ -28,26 +34,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,10 +87,40 @@ import org.jetbrains.annotations.Nullable; @Slf4j public class CfDnsClient extends CfBasicHttpClient { + /** + * Page size used when fetching all zones. Cloudflare allows 5 to 50 zones per page. + */ + static final int ZONES_PER_PAGE = 50; + + private static final int MIN_ZONES_PER_PAGE = 5; + + /** + * Page size used when fetching all DNS records. + */ + static final int MAX_RECORDS_PER_PAGE = 1000; + + /** + * Sort order for listing DNS records. Cloudflare doesn't guarantee a stable order without it, + * so pages could overlap or miss records. + */ + static final String RECORD_ORDER = "order=name&direction=asc"; + + /** + * Max. attempts to fetch all pages consistently. + */ + private static final int MAX_PAGING_ATTEMPTS = 3; + + /** + * Conventional name for the zone apex (the zone name itself). + */ + public static final String APEX = "@"; + private final ResponseValidator responseValidator; private final boolean emptyResultThrowsException; + private final int recordsPerPage; + /** * Constructs a new instance of {@code CfDnsClient}. * @@ -91,13 +131,59 @@ public class CfDnsClient extends CfBasicHttpClient { * @param auth The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth) */ CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfDnsClientBuilder.CfAuth auth) { - super(baseUrl, auth); - this.responseValidator = new ResponseValidator(emptyResultThrowsException); - this.emptyResultThrowsException = emptyResultThrowsException; + this(emptyResultThrowsException, baseUrl, auth, MAX_RECORDS_PER_PAGE); } - private static String buildFqdn(ZoneEntity zone, String sld) { - return sld + "." + zone.getName(); + /** + * Constructs a new instance of {@code CfDnsClient} with a custom page size for fetching all DNS + * records. Intended for tests, which need to fetch multiple pages with only a few records. + */ + CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfDnsClientBuilder.CfAuth auth, + int recordsPerPage) { + this(emptyResultThrowsException, baseUrl, auth, recordsPerPage, + CfDnsClientBuilder.DEFAULT_CONNECT_TIMEOUT, CfDnsClientBuilder.DEFAULT_RESPONSE_TIMEOUT); + } + + /** + * Constructs a new instance of {@code CfDnsClient} with all settings. + */ + CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfDnsClientBuilder.CfAuth auth, + int recordsPerPage, Duration connectTimeout, Duration responseTimeout) { + super(baseUrl, auth, connectTimeout, responseTimeout); + this.responseValidator = new ResponseValidator(emptyResultThrowsException); + this.emptyResultThrowsException = emptyResultThrowsException; + this.recordsPerPage = recordsPerPage; + } + + /** + * Characters which can't be part of a DNS name, but are typical for injection attempts. Further + * validation is done by Cloudflare; the values are URL-encoded anyway. A slash isn't rejected, + * because it's valid in classless reverse delegation names (RFC 2317). + */ + private static final Pattern INVALID_NAME_CHARS = Pattern.compile("[\\s\\p{Cntrl}\\\\?#&;|<>\"'`]"); + + /** + * Validates a zone name or subdomain before it's used in a request. + * + * @throws IllegalArgumentException if the name is {@code null}, blank or contains invalid + * characters + */ + private static String validateName(String name, String kind) { + if (name == null || name.isBlank()) { + throw new IllegalArgumentException(kind + " must not be null or blank"); + } + if (INVALID_NAME_CHARS.matcher(name).find()) { + throw new IllegalArgumentException("Invalid characters in " + kind + ": " + name); + } + return name; + } + + private static String buildFqdn(ZoneEntity zone, String subdomain) { + validateName(subdomain, "subdomain"); + if (APEX.equals(subdomain)) { + return zone.getName(); + } + return subdomain + "." + zone.getName(); } /** @@ -129,33 +215,46 @@ 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 + * @throws IllegalArgumentException if the name is blank or contains invalid characters */ 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. + * Cloudflare requires a page size between 5 and 50 for this endpoint. * * @param pagingRequest the pagination request object containing parameters for paging and * filtering zone data * @return a list of {@code ZoneEntity} objects representing the DNS zones retrieved from the API * @throws CloudflareApiException if there is an error during the API request or response * processing + * @throws IllegalArgumentException if the page size is outside the range 5 to 50 */ public List zoneList(PagingRequest pagingRequest) throws CloudflareApiException { + if (pagingRequest.getPerPage() < MIN_ZONES_PER_PAGE + || pagingRequest.getPerPage() > ZONES_PER_PAGE) { + throw new IllegalArgumentException("Zone page size must be between " + MIN_ZONES_PER_PAGE + + " and " + ZONES_PER_PAGE); + } String endpoint = pagingRequest.addQueryString(CfRequest.ZONE_LIST.buildPath()); ZoneMultipleResponse response = getRequest(endpoint, ZoneMultipleResponse.class); checkResponse(response); @@ -166,112 +265,119 @@ 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. + * @throws IllegalArgumentException if the name is blank or contains invalid characters */ + @Nullable public ZoneEntity zoneGet(String name) throws CloudflareApiException { - String endpoint = CfRequest.ZONE_INFO.buildPath(name); + String endpoint = CfRequest.ZONE_INFO.buildPath(validateName(name, "zone 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 using the maximum supported page size. + * For a specific page, Cloudflare allows a page size between 1 and 5,000,000. * @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 = appendQuery(CfRequest.RECORD_LIST.buildPath(zone.getId()), RECORD_ORDER); + if (pagingRequest == null) { + return filterAndSetZoneRecords(zone, null, + getAllPages(path, RecordMultipleResponse.class, PagingRequest.MAX_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 + * @throws IllegalArgumentException if the subdomain is blank or contains invalid characters */ - 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 = appendQuery( + addTypeFilter(CfRequest.RECORD_LIST_NAME.buildPath(zone.getId(), fqdn), types), RECORD_ORDER); + List recs = getAllPages(endpoint, RecordMultipleResponse.class, recordsPerPage); 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 = appendQuery( + addTypeFilter(CfRequest.RECORD_LIST.buildPath(zone.getId()), types), RECORD_ORDER); + List recs = getAllPages(endpoint, RecordMultipleResponse.class, recordsPerPage); 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. + * @throws IllegalArgumentException if the subdomain is blank or contains invalid characters */ - 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); } @@ -298,18 +404,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 +433,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 +444,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,46 +454,56 @@ 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; } /** - * Deletes DNS records of a specific type within a given zone if they exist. If no record of the - * specified type exists, it logs this occurrence without throwing an exception. + * Attempts to delete DNS records of the specified types within a given zone. If no record types + * are specified, all types for the subdomain are selected. If no matching record exists, this is + * treated as a no-op. Deletions are attempted independently; an error deleting an individual + * record is logged and processing continues. No per-record result is returned, so a normal return + * does not guarantee that every selected record was deleted. * * @param zone The DNS zone entity in which the record exists. - * @param sld The second-level domain for which the record is being checked. - * @param recordTypes The types of DNS records that should be deleted if they exist. - * @throws CloudflareApiException If an error occurs during API communication. + * @param subdomain The subdomain relative to the zone for which the records are being checked. + * @param recordTypes The DNS record types to delete; if empty or {@code null}, all types are selected. + * @throws CloudflareApiException If an error occurs while retrieving the records to delete. + * @throws IllegalArgumentException if the subdomain is blank or contains invalid characters */ - 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 +527,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 +536,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 +556,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 +586,130 @@ 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 appendQuery(endpoint, "type=" + types[0].getType()); + } + + private static String appendQuery(String endpoint, String query) { + return endpoint + (endpoint.contains("?") ? "&" : "?") + query; + } + + 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. + * + *

Entries are de-duplicated by their ID. If fewer entries than announced by the API were + * fetched (e.g. because of concurrent changes), the pages are fetched again, up to + * {@value #MAX_PAGING_ATTEMPTS} times. + * + * @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 result = List.of(); + for (int attempt = 1; attempt <= MAX_PAGING_ATTEMPTS; attempt++) { + PagingResult paged = fetchAllPagesOnce(endpoint, responseType, perPage); + result = paged.entries(); + if (paged.expectedCount() < 0 || result.size() >= paged.expectedCount()) { + return result; + } + log.debug("Fetched {} of {} entries from {} (attempt {}), fetching again.", result.size(), + paged.expectedCount(), endpoint, attempt); + } + log.warn("Paging of {} was inconsistent, the result may be incomplete.", endpoint); + return result; + } + + private record PagingResult(List entries, int expectedCount) { + } + + private > PagingResult fetchAllPagesOnce( + String endpoint, Class responseType, int perPage) throws CloudflareApiException { + Map byId = new LinkedHashMap<>(); + List withoutId = new ArrayList<>(); + int expectedCount = -1; + int page = 1; + while (true) { + String pagedEndpoint = PagingRequest.of(page, perPage).addQueryString(endpoint); + R resp = getRequest(pagedEndpoint, responseType); + checkResponse(resp); + List pageResult = resp.getResult(); + if (pageResult != null) { + for (E entry : pageResult) { + if (entry.getId() == null) { + withoutId.add(entry); + } else { + byId.putIfAbsent(entry.getId(), entry); + } + } + } + ResultInfo info = resp.getResultInfo(); + if (info != null && page == 1) { + expectedCount = info.totalCount(); + } + log.debug("Fetched page {} of {} from {}: {} entries, total {}", page, + info == null ? "?" : info.totalPages(), endpoint, + pageResult == null ? 0 : pageResult.size(), info == null ? "?" : info.totalCount()); + if (info == null || pageResult == null || pageResult.isEmpty() || page >= info.totalPages()) { + List all = new ArrayList<>(byId.values()); + all.addAll(withoutId); + return new PagingResult<>(all, info == null || page == 1 ? -1 : expectedCount); + } + page++; } } diff --git a/src/main/java/codes/thischwa/cf/CfDnsClientBuilder.java b/src/main/java/codes/thischwa/cf/CfDnsClientBuilder.java index c779b68..ce45462 100644 --- a/src/main/java/codes/thischwa/cf/CfDnsClientBuilder.java +++ b/src/main/java/codes/thischwa/cf/CfDnsClientBuilder.java @@ -1,7 +1,10 @@ package codes.thischwa.cf; +import java.net.URI; +import java.time.Duration; +import java.util.Locale; +import java.util.Set; import org.apache.hc.core5.http.ClassicHttpRequest; -import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; /** @@ -16,8 +19,25 @@ public class CfDnsClientBuilder { */ public static final String DEFAULT_BASEURL = "https://api.cloudflare.com/client/v4"; + /** + * The default timeout for establishing a connection. + */ + public static final Duration DEFAULT_CONNECT_TIMEOUT = Duration.ofSeconds(10); + + /** + * The default timeout for waiting for the response data. + */ + public static final Duration DEFAULT_RESPONSE_TIMEOUT = Duration.ofSeconds(30); + + /** + * Hosts for which plain HTTP is allowed (e.g. for local tests). + */ + private static final Set LOOPBACK_HOSTS = Set.of("localhost", "127.0.0.1", "[::1]", "::1"); + private boolean emptyResultThrowsException; private CfAuth auth; + private Duration connectTimeout = DEFAULT_CONNECT_TIMEOUT; + private Duration responseTimeout = DEFAULT_RESPONSE_TIMEOUT; @Nullable private String baseUrl; @@ -42,14 +62,89 @@ public class CfDnsClientBuilder { * Sets the base URL to be used by the {@code CfDnsClient}. * This method allows configuring the base URL for API requests, overriding any default value. * - * @param baseUrl the base URL to be used for API requests + *

To protect the credentials, the URL must use HTTPS. Plain HTTP is only allowed for + * loopback hosts (e.g. {@code localhost}) for testing purposes. + * + * @param baseUrl the base URL to be used for API requests, {@code null} resets it to + * {@link #DEFAULT_BASEURL} * @return the current instance of {@code CfDnsClientBuilder}, enabling method chaining + * @throws IllegalArgumentException if the URL is invalid or doesn't use HTTPS */ - public CfDnsClientBuilder withBaseUrl(String baseUrl) { - this.baseUrl = baseUrl; + public CfDnsClientBuilder withBaseUrl(@Nullable String baseUrl) { + this.baseUrl = baseUrl == null ? null : validateBaseUrl(baseUrl); return this; } + /** + * Sets the timeout for establishing a connection. Default is {@link #DEFAULT_CONNECT_TIMEOUT}. + * + * @param connectTimeout the connect timeout, must be positive + * @return the current instance of {@code CfDnsClientBuilder}, enabling method chaining + * @throws IllegalArgumentException if the timeout is {@code null}, zero or negative + */ + public CfDnsClientBuilder withConnectTimeout(Duration connectTimeout) { + this.connectTimeout = validateTimeout(connectTimeout, "Connect timeout"); + return this; + } + + /** + * Sets the timeout for waiting for the response data. Default is + * {@link #DEFAULT_RESPONSE_TIMEOUT}. + * + * @param responseTimeout the response timeout, must be positive + * @return the current instance of {@code CfDnsClientBuilder}, enabling method chaining + * @throws IllegalArgumentException if the timeout is {@code null}, zero or negative + */ + public CfDnsClientBuilder withResponseTimeout(Duration responseTimeout) { + this.responseTimeout = validateTimeout(responseTimeout, "Response timeout"); + return this; + } + + private static Duration validateTimeout(Duration timeout, String name) { + if (timeout == null || timeout.isZero() || timeout.isNegative()) { + throw new IllegalArgumentException(name + " must be positive: " + timeout); + } + long millis; + try { + millis = timeout.toMillis(); + } catch (ArithmeticException e) { + throw new IllegalArgumentException(name + " is too large: " + timeout, e); + } + // the HTTP client works with milliseconds, 0 ms would disable the timeout + if (millis < 1) { + throw new IllegalArgumentException(name + " must be at least 1 ms: " + timeout); + } + return timeout; + } + + private static String validateBaseUrl(String baseUrl) { + URI uri; + try { + uri = URI.create(baseUrl.strip()); + } catch (IllegalArgumentException e) { + throw new IllegalArgumentException("Invalid base URL: " + baseUrl, e); + } + String scheme = uri.getScheme() == null ? "" : uri.getScheme().toLowerCase(Locale.ROOT); + String host = uri.getHost(); + if (host == null || host.isBlank()) { + throw new IllegalArgumentException("Base URL must contain a host: " + baseUrl); + } + if (uri.getRawQuery() != null || uri.getRawFragment() != null) { + throw new IllegalArgumentException("Base URL must not contain a query or fragment: " + baseUrl); + } + boolean https = "https".equals(scheme); + boolean loopbackHttp = "http".equals(scheme) && LOOPBACK_HOSTS.contains(host.toLowerCase(Locale.ROOT)); + if (!https && !loopbackHttp) { + throw new IllegalArgumentException("Base URL must use HTTPS: " + baseUrl); + } + String normalized = uri.toString(); + // avoid double slashes when appending the endpoint paths + while (normalized.endsWith("/")) { + normalized = normalized.substring(0, normalized.length() - 1); + } + return normalized; + } + /** * Configures the authentication method for the {@code CfDnsClient} to use an API token. * This is the recommended way to authenticate with the Cloudflare API, as it provides @@ -92,10 +187,16 @@ public class CfDnsClientBuilder { * @return a new instance of {@code CfDnsClient} configured with the * specified options such as base URL, authentication details, * and the exception-handling policy for empty results. + * @throws IllegalStateException if no authentication was configured */ public CfDnsClient build() { + if (auth == null) { + throw new IllegalStateException( + "No authentication configured, use withApiTokenAuth(...) or withEmailKeyAuth(...)"); + } String url = baseUrl == null ? DEFAULT_BASEURL : baseUrl; - return new CfDnsClient(emptyResultThrowsException, url, auth); + return new CfDnsClient(emptyResultThrowsException, url, auth, CfDnsClient.MAX_RECORDS_PER_PAGE, + connectTimeout, responseTimeout); } /** @@ -128,8 +229,8 @@ public class CfDnsClientBuilder { * @param apiToken the Cloudflare API token * @throws IllegalArgumentException if the API token is null or blank */ - ApiTokenAuth(@NotNull String apiToken) { - if (apiToken.isBlank()) { + ApiTokenAuth(String apiToken) { + if (apiToken == null || apiToken.isBlank()) { throw new IllegalArgumentException("API token must not be null or blank!"); } this.apiToken = apiToken; @@ -157,11 +258,11 @@ public class CfDnsClientBuilder { * @param authKey the API key of the Cloudflare account * @throws IllegalArgumentException if email or key is null or blank */ - EmailKeyAuth(@NotNull String authEmail, @NotNull String authKey) { - if (authEmail.isBlank()) { + EmailKeyAuth(String authEmail, String authKey) { + if (authEmail == null || authEmail.isBlank()) { throw new IllegalArgumentException("Authentication email must not be null or blank!"); } - if (authKey.isBlank()) { + if (authKey == null || authKey.isBlank()) { throw new IllegalArgumentException("Authentication key must not be null or blank!"); } this.authEmail = authEmail; diff --git a/src/main/java/codes/thischwa/cf/CfRequest.java b/src/main/java/codes/thischwa/cf/CfRequest.java index 83f7165..70ad41b 100644 --- a/src/main/java/codes/thischwa/cf/CfRequest.java +++ b/src/main/java/codes/thischwa/cf/CfRequest.java @@ -1,5 +1,9 @@ package codes.thischwa.cf; +import java.net.URLEncoder; +import java.nio.charset.StandardCharsets; +import java.util.regex.Matcher; +import java.util.regex.Pattern; import lombok.Getter; /** @@ -18,46 +22,54 @@ public enum CfRequest { * name. The endpoint path supports a placeholder for the zone name, which needs to be provided to * construct the complete path. */ - ZONE_INFO("/zones?name=%s"), + ZONE_INFO("/zones?name={value}"), /** * Represents the API endpoint path for retrieving information about DNS records within a * specific DNS zone. The endpoint path includes a placeholder for the zone identifier, which * needs to be provided to construct the complete path. */ - RECORD_LIST("/zones/%s/dns_records"), + RECORD_LIST("/zones/{id}/dns_records"), /** * Represents the API endpoint path for retrieving information about a DNS record within a * specific DNS zone by its name. The endpoint path includes placeholders for the zone identifier * and the record name, which need to be provided to construct the complete path. */ - RECORD_LIST_NAME("/zones/%s/dns_records?name=%s"), + RECORD_LIST_NAME("/zones/{id}/dns_records?name={value}"), /** * Represents the API endpoint path for creating a new DNS record within a specific DNS zone. The * endpoint path includes a placeholder for the zone identifier, which needs to be provided to * construct the complete path. */ - RECORD_CREATE("/zones/%s/dns_records"), + RECORD_CREATE("/zones/{id}/dns_records"), /** * Represents the API endpoint path for updating an existing DNS record within a specific DNS * zone. The endpoint path includes placeholders for the zone identifier and the record * identifier, which need to be provided to construct the complete path. */ - RECORD_UPDATE("/zones/%s/dns_records/%s"), + RECORD_UPDATE("/zones/{id}/dns_records/{id}"), /** * Represents the API endpoint path for performing batch operations on DNS records within a specific zone. - * The placeholder "%s" in the path is intended to be replaced by a zone identifier. + * The placeholder in the path is intended to be replaced by a zone identifier. * This constant is used to construct the URL for interacting with the batch DNS records API. */ - RECORD_BATCH("/zones/%s/dns_records/batch"), + RECORD_BATCH("/zones/{id}/dns_records/batch"), /** * Represents the API endpoint path for deleting an existing DNS record within a specific DNS * zone. The endpoint path includes placeholders for the zone identifier and the record * identifier, which need to be provided to construct the complete path. */ - RECORD_DELETE("/zones/%s/dns_records/%s"); + RECORD_DELETE("/zones/{id}/dns_records/{id}"); + + private static final String ID_PLACEHOLDER = "{id}"; + private static final Pattern PLACEHOLDER = Pattern.compile("\\{(id|value)}"); + + /** + * Allowed characters of Cloudflare identifiers (zone and record IDs). Prevents e.g. path + * traversal with IDs like "../..". + */ + private static final Pattern ID_PATTERN = Pattern.compile("[A-Za-z0-9]{1,64}"); - private static final char VAR_IDENTIFICATION = '%'; private final String path; CfRequest(String path) { @@ -65,21 +77,45 @@ public enum CfRequest { } /** - * Constructs the complete API endpoint path by formatting the base path with the provided - * arguments. + * Constructs the complete API endpoint path by replacing the placeholders with the provided + * arguments. Identifiers ({@code {id}}) are validated, query values ({@code {value}}) are + * URL-encoded. * - * @param vars the arguments to format the path string with; these are typically specific - * identifiers or parameters required by the API endpoint. + * @param vars the arguments to replace the placeholders with, in the order of the placeholders * @return the fully constructed API endpoint path as a string. + * @throws IllegalArgumentException if the number of arguments doesn't match the placeholders, an + * argument is {@code null} or an identifier is invalid */ String buildPath(Object... vars) { - long varCount = path.chars().filter(c -> c == VAR_IDENTIFICATION).count(); + Matcher matcher = PLACEHOLDER.matcher(path); + long varCount = matcher.results().count(); if (varCount != vars.length) { throw new IllegalArgumentException( String.format( "The number of variables (%d) does not match the number of parameters (%d) in the path string: %s", vars.length, varCount, path)); } - return String.format(path, vars); + matcher.reset(); + StringBuilder sb = new StringBuilder(); + int i = 0; + while (matcher.find()) { + Object arg = vars[i++]; + if (arg == null) { + throw new IllegalArgumentException("Path variable must not be null: " + path); + } + String value = arg.toString(); + String replacement; + if (ID_PLACEHOLDER.equals(matcher.group())) { + if (!ID_PATTERN.matcher(value).matches()) { + throw new IllegalArgumentException("Invalid identifier: " + value); + } + replacement = value; + } else { + replacement = URLEncoder.encode(value, StandardCharsets.UTF_8); + } + matcher.appendReplacement(sb, Matcher.quoteReplacement(replacement)); + } + matcher.appendTail(sb); + return sb.toString(); } } 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/RecordOperations.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java index 579300b..fda6911 100644 --- a/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java +++ b/src/main/java/codes/thischwa/cf/fluent/RecordOperations.java @@ -40,10 +40,15 @@ public interface RecordOperations { RecordEntity update(String newContent) throws CloudflareApiException; /** - * Deletes DNS records of the specified types. + * Deletes DNS records of the specified types for the selected subdomain. The types passed here + * determine which records are deleted, independently of any type filter used to select the + * subdomain. If no types are specified, records of all types for that subdomain are selected for + * deletion. A {@link CloudflareApiException} from an individual deletion is logged and does not + * stop later attempts. No per-record result is returned, so returning normally does not guarantee + * that all selected records were deleted. * * @param types the DNS record types to delete - * @throws CloudflareApiException if an error occurs while deleting records + * @throws CloudflareApiException if an error occurs while retrieving records to delete */ void delete(RecordType... types) throws CloudflareApiException; } diff --git a/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java b/src/main/java/codes/thischwa/cf/fluent/RecordOperationsImpl.java index 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..a404620 100644 --- a/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java +++ b/src/main/java/codes/thischwa/cf/fluent/ZoneOperations.java @@ -13,26 +13,31 @@ 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. + *

    + * The type filter does not restrict a subsequent {@link RecordOperations#delete(RecordType...)} call; + * that method uses its own type arguments, and calling it without arguments deletes all record types + * for the selected subdomain. A {@link CloudflareApiException} from an individual deletion is + * logged and does not stop later attempts; see {@link RecordOperations#delete(RecordType...)}. * - * @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/PagingRequest.java b/src/main/java/codes/thischwa/cf/model/PagingRequest.java index 773d002..baf4796 100644 --- a/src/main/java/codes/thischwa/cf/model/PagingRequest.java +++ b/src/main/java/codes/thischwa/cf/model/PagingRequest.java @@ -7,7 +7,9 @@ import lombok.Data; * Represents a request model for paginated data. * *

    This class encapsulates the page number and the number of items per page for a paginated - * request, along with utility methods for constructing and retrieving pagination parameters. + * request, along with utility methods for constructing and retrieving pagination parameters. Page + * numbers must be at least 1, and page sizes must be between 1 and 5,000,000 for DNS record requests. + * Zone requests have the more restrictive Cloudflare limit of 5 to 50 items per page. * *

    Key functionalities: * @@ -22,52 +24,83 @@ import lombok.Data; @Data public class PagingRequest { /** - * Default page size for retrieving all records in a single request. - * Set to a very high value to effectively disable pagination when fetching all records. + * Default page size for a single request, which is within the limits for zones and DNS records. */ - private static final int DEFAULT_ALL_RECORDS_PAGE_SIZE = 1000; + private static final int DEFAULT_PAGE_SIZE = 50; + + /** + * Maximum number of DNS records allowed per page by Cloudflare. + */ + public static final int MAX_PER_PAGE = 5_000_000; private int page; private int perPage; PagingRequest(int page, int perPage) { - this.page = page; - this.perPage = perPage; + this.page = validatePage(page); + this.perPage = validatePerPage(perPage); } /** * Creates a new {@code PagingRequest} instance with the specified page number and items per page. + * The page must be at least 1, and the page size must be between 1 and 5,000,000. Zone requests + * have a more restrictive page-size range of 5 to 50, enforced by {@code zoneList}. * * @param page the page number to be requested * @param perPage the number of items to be included per page * @return a new {@code PagingRequest} instance with the provided parameters + * @throws IllegalArgumentException if the page or page size is outside the allowed range */ public static PagingRequest of(int page, int perPage) { return new PagingRequest(page, perPage); } /** - * Creates a default {@code PagingRequest} instance with a page number set to 1 and a high number - * of items per page to accommodate large dataset requests and effectively retrieve all records. + * Creates a default {@code PagingRequest} instance for page 1 with 50 items per page. This is a + * request for one page; it does not fetch additional pages. * * @return a default {@code PagingRequest} instance with predefined pagination parameters */ public static PagingRequest defaultPaging() { - return new PagingRequest(1, DEFAULT_ALL_RECORDS_PAGE_SIZE); + return new PagingRequest(1, DEFAULT_PAGE_SIZE); + } + + /** + * Sets the page number. + * + * @param page the page number, which must be at least 1 + * @throws IllegalArgumentException if the page number is less than 1 + */ + public void setPage(int page) { + this.page = validatePage(page); + } + + /** + * Sets the number of items per page. + * + * @param perPage the page size, between 1 and 5,000,000 for DNS record requests + * @throws IllegalArgumentException if the page size is outside the allowed range + */ + public void setPerPage(int perPage) { + this.perPage = validatePerPage(perPage); } /** * Retrieves the pagination parameters in a key-value map format. * * @return a map containing the pagination parameters, where the key "page" indicates the current - * page number and the key "perPage" indicates the number of items per page. + * page number and the key "perPage" indicates the number of items per page. The map key is + * intentionally named "perPage"; Cloudflare's query parameter is "per_page". Use + * {@link #addQueryString(String)} to build a Cloudflare-compatible query string. */ public Map getPagingParams() { return Map.of("page", String.valueOf(page), "perPage", String.valueOf(perPage)); } /** - * Appends a query string with pagination parameters (page and perPage) to the provided endpoint. + * Appends a query string with pagination parameters ({@code page} and {@code per_page}) to the + * provided endpoint. Unlike {@link #getPagingParams()}, this method uses Cloudflare's + * {@code per_page} query parameter name. * * @param endpoint the base URL or API endpoint to which the query string will be appended * @return the complete URL with the appended query string for pagination @@ -80,4 +113,18 @@ public class PagingRequest { String qs = "page=" + page + "&per_page=" + perPage; return add ? "&" + qs : "?" + qs; } + + private static int validatePage(int page) { + if (page < 1) { + throw new IllegalArgumentException("page must be at least 1"); + } + return page; + } + + private static int validatePerPage(int perPage) { + if (perPage < 1 || perPage > MAX_PER_PAGE) { + throw new IllegalArgumentException("perPage must be between 1 and " + MAX_PER_PAGE); + } + return perPage; + } } diff --git a/src/main/java/codes/thischwa/cf/model/RecordEntity.java b/src/main/java/codes/thischwa/cf/model/RecordEntity.java index 7fb32d3..2f8f017 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 and URI records (for SRV records it's part of the data). + *
  • 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,46 @@ 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 and URI records. For SRV records the priority is + * part of {@link #data}. + */ + @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 "priority", "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 +146,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 +180,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..0193b7f --- /dev/null +++ b/src/test/java/codes/thischwa/cf/CfBasicHttpClientErrorTest.java @@ -0,0 +1,171 @@ +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.net.SocketTimeoutException; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +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; + private volatile String lastPath; + private volatile long delayMillis; + + @BeforeEach + void setUp() throws IOException { + server = HttpServer.create(new InetSocketAddress("localhost", 0), 0); + server.createContext("/", exchange -> { + requestCount.incrementAndGet(); + lastPath = exchange.getRequestURI().getRawPath(); + if (delayMillis > 0) { + try { + Thread.sleep(delayMillis); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + 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()); + } + + @Test + void trailingSlashOfBaseUrlIsRemoved() throws Exception { + respond(200, ZONE_JSON); + try (CfDnsClient slashClient = new CfDnsClientBuilder() + .withApiTokenAuth("test-token") + .withBaseUrl("http://localhost:" + server.getAddress().getPort() + "/client/v4/") + .build()) { + slashClient.zoneList(); + } + assertEquals("/client/v4/zones", lastPath); + } + + @Test + void responseTimeoutIsApplied() throws Exception { + respond(200, ZONE_JSON); + delayMillis = 2000; + try (CfDnsClient timeoutClient = new CfDnsClientBuilder() + .withApiTokenAuth("test-token") + .withBaseUrl("http://localhost:" + server.getAddress().getPort()) + .withResponseTimeout(Duration.ofMillis(200)) + .build()) { + long start = System.nanoTime(); + CloudflareApiException e = assertThrows(CloudflareApiException.class, timeoutClient::zoneList); + long elapsedMillis = (System.nanoTime() - start) / 1_000_000; + assertInstanceOf(SocketTimeoutException.class, e.getCause()); + assertTrue(elapsedMillis < 1500, "timeout not applied, elapsed: " + elapsedMillis); + } finally { + delayMillis = 0; + } + } +} 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..3b74aaf 100644 --- a/src/test/java/codes/thischwa/cf/CfClientTest.java +++ b/src/test/java/codes/thischwa/cf/CfClientTest.java @@ -1,8 +1,11 @@ package codes.thischwa.cf; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; @@ -13,6 +16,7 @@ import codes.thischwa.cf.model.PagingRequest; import codes.thischwa.cf.model.RecordEntity; import codes.thischwa.cf.model.RecordType; import codes.thischwa.cf.model.ZoneEntity; +import java.time.Instant; import java.util.ArrayList; import java.util.Arrays; import java.util.HashSet; @@ -36,6 +40,9 @@ public class CfClientTest { private final CfDnsClient client = new CfDnsClientBuilder().withEmptyResultThrowsException(true).withApiTokenAuth(API_TOKEN).build(); + private static final String IP_PREFIX = "130.0.0."; + private static final String UPDATED_IP_PREFIX = "130.1.0."; + @BeforeAll static void checkEnv() { assumeTrue(API_TOKEN != null && !API_TOKEN.isBlank(), "API_TOKEN not set; skipping client tests"); @@ -44,7 +51,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 +65,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 +86,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 { @@ -102,7 +109,7 @@ public class CfClientTest { assertFalse(zones.isEmpty()); assertEquals(ZONE_STR, zones.get(0).getName()); - zones = client.zoneList(PagingRequest.of(1, 100)); + zones = client.zoneList(PagingRequest.of(1, 50)); assertNotNull(zones); assertFalse(zones.isEmpty()); assertEquals(ZONE_STR, zones.get(0).getName()); @@ -114,7 +121,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 +156,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 +165,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 +181,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()); @@ -187,8 +194,9 @@ public class CfClientTest { } } - // test recordList without SLD - List fullList = client.recordList(z); + // test recordList without SLD (the unfiltered list may lag behind directly after creating records) + List fullList = awaitRecords(() -> client.recordList(z), + recs -> recs.stream().anyMatch(re -> re.getId().equals(createdRe2.getId()))); assertTrue(fullList.size() >= 2); assertTrue(fullList.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); assertTrue(fullList.stream().anyMatch(re -> re.getId().equals(createdRe2.getId()))); @@ -196,7 +204,8 @@ 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 = awaitRecords(() -> client.recordListByType(z, RecordType.A), + recs -> recs.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); assertFalse(aList.isEmpty()); assertTrue(aList.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); assertTrue(aList.stream().noneMatch(re -> re.getId().equals(createdRe2.getId()))); @@ -207,16 +216,21 @@ public class CfClientTest { assertFalse(fluentList.isEmpty()); assertTrue(fluentList.stream().anyMatch(re -> re.getId().equals(createdRe1.getId()))); - // update AAAA record + // update AAAA record, the given record (incl. its timestamps) must not be modified createdRe2.setContent("2a0a:4cc0:c0:2e4::2"); - client.recordUpdate(z, createdRe2); - aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA); + Instant createdOn = createdRe2.getCreatedOn(); + RecordEntity updatedRe2 = client.recordUpdate(z, createdRe2); + assertEquals(createdOn, createdRe2.getCreatedOn()); + assertNotNull(createdRe2.getModifiedOn()); + assertEquals("2a0a:4cc0:c0:2e4::2", updatedRe2.getContent()); + assertEquals(z.getId(), updatedRe2.getZoneId()); + 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 +238,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 { @@ -246,10 +260,6 @@ public class CfClientTest { assertTrue(exception.getMessage().contains("Must be one of:")); } - private static final String IP_PREFIX = "130.0.0."; - private static final String UPDATED_IP_PREFIX = "130.1.0."; - - @Test void testBatch() throws Exception { // starting point: already existing zone 'mein-d-ns.de' @@ -303,7 +313,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 +323,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 +333,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 +343,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 +353,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 +369,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 +378,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 +386,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 +403,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 @@ -465,6 +475,7 @@ public class CfClientTest { void testPaging() throws Exception { ZoneEntity zone = client.zoneGet(ZONE_STR); String pagingSld = "paging-" + System.currentTimeMillis(); + List createdRecords = new ArrayList<>(); try { int existingCount = 0; @@ -480,10 +491,11 @@ public class CfClientTest { int targetCount = 12; int recordsToCreate = Math.max(0, targetCount - existingCount); - // Create additional A records if needed - List createdRecords = new ArrayList<>(); + // Create additional A records if needed. Each record gets its own name, so the order by name + // is unambiguous (Cloudflare doesn't guarantee a stable order of records with the same name). for (int i = 1; i <= recordsToCreate; i++) { - RecordEntity record = RecordEntity.build(pagingSld, RecordType.A, TTL, "127.0.0." + i); + String name = String.format("%s-%02d.%s", pagingSld, i, ZONE_STR); + RecordEntity record = RecordEntity.build(name, RecordType.A, TTL, "127.0.0." + i); RecordEntity created = client.recordCreate(zone, record); createdRecords.add(created); assertNotNull(created.getId()); @@ -518,11 +530,233 @@ public class CfClientTest { Set allRecordIds = allRecords.stream().map(RecordEntity::getId).collect(Collectors.toSet()); assertEquals(createdRecords.size(), allRecordIds.size()); assertTrue(allRecordIds.containsAll(generatedRecordIds)); + + // Without PagingRequest all pages must be fetched, also if the page size is small + try (CfDnsClient smallPageClient = new CfDnsClient(true, CfDnsClientBuilder.DEFAULT_BASEURL, + new CfDnsClientBuilder.ApiTokenAuth(API_TOKEN), 5)) { + // a new client (connection) may see a lagging state of the record list for a short time + Set smallPageIds = awaitRecords(() -> smallPageClient.recordList(zone), + recs -> recs.size() >= allRecordIds.size()).stream() + .map(RecordEntity::getId).collect(Collectors.toSet()); + assertEquals(allRecordIds, smallPageIds); + assertEquals(createdRecords.size(), awaitRecords( + () -> smallPageClient.recordListByType(zone, RecordType.A), + recs -> recs.size() >= createdRecords.size()).size()); + assertEquals(1, smallPageClient.recordListBySubdomain(zone, pagingSld + "-01").size()); + } + } finally { + deleteQuietly(zone, createdRecords); + } + } + + @Test + void testApiErrorDetails() throws Exception { + ZoneEntity zone = client.zoneGet(ZONE_STR); + String sub = "invalid-" + System.currentTimeMillis(); + try { + // an A record with an invalid IP is rejected by Cloudflare + CloudflareApiException e = assertThrows(CloudflareApiException.class, + () -> client.recordCreateSubdomain(zone, sub, TTL, RecordType.A, "not-an-ip")); + assertEquals(CloudflareApiException.class, e.getClass()); + assertEquals(400, e.getStatusCode()); + assertFalse(e.getErrors().isEmpty()); + assertTrue(e.getErrors().get(0).getCode() > 0); + // the Cloudflare error message is part of the exception message, not wrapped + assertTrue(e.getMessage().contains(e.getErrors().get(0).getMessage()), e.getMessage()); } finally { try { - client.recordDeleteTypeIfExists(zone, pagingSld, RecordType.A); + client.recordDeleteTypeIfExists(zone, sub, RecordType.A); } catch (Exception e) { /* ignore */ } } } + @Test + void testRecordDeleteUnknownId() throws Exception { + ZoneEntity zone = client.zoneGet(ZONE_STR); + CloudflareApiException e = assertThrows(CloudflareApiException.class, + () -> client.recordDelete(zone, "0123456789abcdef0123456789abcdef")); + assertInstanceOf(CloudflareNotFoundException.class, e); + assertEquals(404, e.getStatusCode()); + assertFalse(e.getErrors().isEmpty()); + } + + @Test + void testZoneNotFound() throws Exception { + String unknownZone = "not-existing-" + System.currentTimeMillis() + ".de"; + // emptyResultThrowsException = true + assertThrows(CloudflareNotFoundException.class, () -> client.zoneGet(unknownZone)); + assertThrows(CloudflareNotFoundException.class, () -> client.zone(unknownZone)); + + // emptyResultThrowsException = false + try (CfDnsClient lenientClient = new CfDnsClientBuilder().withApiTokenAuth(API_TOKEN).build()) { + assertNull(lenientClient.zoneGet(unknownZone)); + assertThrows(CloudflareNotFoundException.class, () -> lenientClient.zone(unknownZone)); + assertNotNull(lenientClient.zoneGet(ZONE_STR)); + } + } + + @Test + void testClientClose() throws Exception { + CfDnsClient closeableClient = new CfDnsClientBuilder().withApiTokenAuth(API_TOKEN).build(); + // multiple requests with the same client + assertNotNull(closeableClient.zoneGet(ZONE_STR)); + assertFalse(closeableClient.zoneList().isEmpty()); + assertDoesNotThrow(closeableClient::close); + } + + @Test + void testMultiLevelSubdomainAndApex() throws Exception { + ZoneEntity zone = client.zoneGet(ZONE_STR); + String multiLevel = "a.b-" + System.currentTimeMillis(); + String apexContent = "cf-client-test-" + System.currentTimeMillis(); + List created = new ArrayList<>(); + try { + // multi-level subdomain + RecordEntity rec = client.recordCreateSubdomain(zone, multiLevel, TTL, RecordType.A, "130.0.0.10"); + created.add(rec); + assertEquals(multiLevel + "." + ZONE_STR, rec.getName()); + assertEquals(multiLevel, rec.getSubdomain()); + List fetched = client.recordListBySubdomain(zone, multiLevel, RecordType.A); + assertEquals(1, fetched.size()); + assertEquals(multiLevel, fetched.get(0).getSubdomain()); + assertEquals(ZONE_STR, fetched.get(0).getZoneName()); + + // batch with a multi-level name must not cut the name + String batchName = "c.d-" + System.currentTimeMillis() + "." + ZONE_STR; + BatchEntry batchResult = client.recordBatch(zone, + List.of(RecordEntity.build(batchName, RecordType.A, TTL, "130.0.0.11")), null, null, null); + RecordEntity batched = batchResult.getPosts().get(0); + created.add(batched); + assertEquals(batchName, batched.getName()); + + // zone apex (TXT record with unique content, existing apex records stay untouched) + RecordEntity apex = client.recordCreateSubdomain(zone, CfDnsClient.APEX, TTL, RecordType.TXT, + "\"" + apexContent + "\""); + created.add(apex); + assertEquals(ZONE_STR, apex.getName()); + assertEquals(CfDnsClient.APEX, apex.getSubdomain()); + assertTrue(client.recordListBySubdomain(zone, CfDnsClient.APEX, RecordType.TXT).stream() + .anyMatch(r -> r.getId().equals(apex.getId()) && CfDnsClient.APEX.equals(r.getSubdomain()))); + } finally { + deleteQuietly(zone, created); + } + } + + @Test + void testTypeFilter() throws Exception { + ZoneEntity zone = client.zoneGet(ZONE_STR); + String sub = "types-" + System.currentTimeMillis(); + List created = new ArrayList<>(); + try { + created.add(client.recordCreateSubdomain(zone, sub, TTL, RecordType.A, "130.0.0.20")); + created.add(client.recordCreateSubdomain(zone, sub, TTL, RecordType.AAAA, "2001:db8::20")); + created.add(client.recordCreateSubdomain(zone, sub, TTL, RecordType.TXT, "\"type filter\"")); + + // one type: filtered by Cloudflare + List txt = client.recordListBySubdomain(zone, sub, RecordType.TXT); + assertEquals(1, txt.size()); + assertEquals(RecordType.TXT.getType(), txt.get(0).getType()); + assertTrue(client.recordListByType(zone, RecordType.TXT).stream() + .allMatch(r -> RecordType.TXT.getType().equals(r.getType()))); + + // multiple types: filtered by the client + List ip = client.recordListBySubdomain(zone, sub, RecordType.A, RecordType.AAAA); + assertEquals(Set.of("A", "AAAA"), ip.stream().map(RecordEntity::getType).collect(Collectors.toSet())); + + // no type: all records + assertEquals(3, client.recordListBySubdomain(zone, sub).size()); + } finally { + deleteQuietly(zone, created); + } + } + + @Test + void testRecordAttributes() throws Exception { + ZoneEntity zone = client.zoneGet(ZONE_STR); + String sub = "attr-" + System.currentTimeMillis(); + List created = new ArrayList<>(); + Instant start = Instant.now().minusSeconds(60); + try { + // MX record with priority and comment + RecordEntity mx = RecordEntity.build(sub + "." + ZONE_STR, RecordType.MX, TTL, "mail." + ZONE_STR); + mx.setPriority(10); + mx.setComment("cf client test"); + RecordEntity createdMx = client.recordCreate(zone, mx); + created.add(createdMx); + assertEquals(10, createdMx.getPriority()); + assertEquals("cf client test", createdMx.getComment()); + assertNull(mx.getId(), "the given record must not be modified"); + // timestamps are Instants (UTC) + assertTrue(createdMx.getCreatedOn().isAfter(start), createdMx.getCreatedOn().toString()); + assertTrue(createdMx.getCreatedOn().isBefore(Instant.now().plusSeconds(60))); + + RecordEntity fetchedMx = client.recordListBySubdomain(zone, sub, RecordType.MX).get(0); + assertEquals(10, fetchedMx.getPriority()); + assertEquals("cf client test", fetchedMx.getComment()); + + // partial update keeps the attributes which aren't sent + RecordEntity updatedMx = client.recordUpdate(zone, RecordEntity.build(fetchedMx.getId(), "mx2." + ZONE_STR)); + assertEquals("mx2." + ZONE_STR, updatedMx.getContent()); + assertEquals(10, updatedMx.getPriority()); + assertEquals("cf client test", updatedMx.getComment()); + + // batch PATCH changes the priority + fetchedMx = client.recordListBySubdomain(zone, sub, RecordType.MX).get(0); + fetchedMx.setPriority(20); + client.recordBatch(zone, null, null, List.of(fetchedMx), null); + assertEquals(20, client.recordListBySubdomain(zone, sub, RecordType.MX).get(0).getPriority()); + + // SRV record with structured data, for SRV records the priority is part of the data + String srvName = "_sip._tcp." + sub + "." + ZONE_STR; + RecordEntity srv = RecordEntity.build(srvName, RecordType.SRV, TTL, null); + srv.setData(Map.of("priority", 10, "weight", 5, "port", 5060, "target", "sip." + ZONE_STR)); + RecordEntity createdSrv = client.recordCreate(zone, srv); + created.add(createdSrv); + assertEquals(srvName, createdSrv.getName()); + assertEquals(10, ((Number) createdSrv.getData().get("priority")).intValue()); + assertEquals(5060, ((Number) createdSrv.getData().get("port")).intValue()); + assertEquals(5, ((Number) createdSrv.getData().get("weight")).intValue()); + assertEquals("sip." + ZONE_STR, createdSrv.getData().get("target")); + } finally { + deleteQuietly(zone, created); + } + } + + private void deleteQuietly(ZoneEntity zone, List records) { + for (RecordEntity rec : records) { + try { + client.recordDelete(zone, rec.getId()); + } catch (Exception e) { + log.warn("Couldn't delete test record {}: {}", rec.getName(), e.getMessage()); + } + } + } + + @FunctionalInterface + private interface RecordQuery { + List get() throws CloudflareApiException; + } + + /** + * Repeats the query until the condition is met. The unfiltered record list of Cloudflare can lag + * behind for a short time after records were created. + */ + private static List awaitRecords(RecordQuery query, + java.util.function.Predicate> condition) + throws CloudflareApiException, InterruptedException { + List recs = List.of(); + for (int attempt = 1; attempt <= 10; attempt++) { + try { + recs = query.get(); + if (condition.test(recs)) { + return recs; + } + } catch (CloudflareNotFoundException e) { + recs = List.of(); + } + log.info("Records not yet listed (attempt {}), waiting ...", attempt); + Thread.sleep(1000); + } + return recs; + } } diff --git a/src/test/java/codes/thischwa/cf/CfDnsClientBuilderTest.java b/src/test/java/codes/thischwa/cf/CfDnsClientBuilderTest.java index aefeeab..cfca4f7 100644 --- a/src/test/java/codes/thischwa/cf/CfDnsClientBuilderTest.java +++ b/src/test/java/codes/thischwa/cf/CfDnsClientBuilderTest.java @@ -4,6 +4,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertThrows; +import java.time.Duration; import org.junit.jupiter.api.Test; /** @@ -147,4 +148,57 @@ class CfDnsClientBuilderTest { assertNotNull(client); } + + @Test + void testBaseUrlMustUseHttps() { + CfDnsClientBuilder builder = new CfDnsClientBuilder().withApiTokenAuth("test-token"); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("http://api.example.com")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("ftp://api.example.com")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("api.example.com")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("https://")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("https://api example.com")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("https://api.example.com/v4?x=1")); + assertThrows(IllegalArgumentException.class, () -> builder.withBaseUrl("https://api.example.com/v4#x")); + } + + @Test + void testBaseUrlAllowsHttpForLoopbackOnly() { + assertNotNull(new CfDnsClientBuilder().withApiTokenAuth("t").withBaseUrl("http://localhost:8080").build()); + assertNotNull(new CfDnsClientBuilder().withApiTokenAuth("t").withBaseUrl("http://127.0.0.1:8080/v4").build()); + assertNotNull(new CfDnsClientBuilder().withApiTokenAuth("t").withBaseUrl("HTTPS://API.example.com/").build()); + assertNotNull(new CfDnsClientBuilder().withApiTokenAuth("t").withBaseUrl(null).build()); + } + + @Test + void testInvalidTimeoutsAreRejected() { + CfDnsClientBuilder builder = new CfDnsClientBuilder(); + assertThrows(IllegalArgumentException.class, () -> builder.withConnectTimeout(null)); + assertThrows(IllegalArgumentException.class, () -> builder.withConnectTimeout(Duration.ZERO)); + assertThrows(IllegalArgumentException.class, () -> builder.withResponseTimeout(Duration.ofSeconds(-1))); + // would become 0 ms = no timeout at all + assertThrows(IllegalArgumentException.class, () -> builder.withResponseTimeout(Duration.ofNanos(500_000))); + assertThrows(IllegalArgumentException.class, () -> builder.withConnectTimeout(Duration.ofNanos(1))); + // would overflow when converted to milliseconds + assertThrows(IllegalArgumentException.class, + () -> builder.withResponseTimeout(Duration.ofSeconds(Long.MAX_VALUE))); + assertNotNull(builder.withApiTokenAuth("t").withResponseTimeout(Duration.ofMillis(1)).build()); + assertNotNull(builder.withApiTokenAuth("t") + .withConnectTimeout(Duration.ofSeconds(1)) + .withResponseTimeout(Duration.ofSeconds(2)) + .build()); + } + + @Test + void testNullCredentialsAreRejected() { + assertThrows(IllegalArgumentException.class, () -> new CfDnsClientBuilder().withApiTokenAuth(null)); + assertThrows(IllegalArgumentException.class, () -> new CfDnsClientBuilder().withEmailKeyAuth(null, "key")); + assertThrows(IllegalArgumentException.class, () -> new CfDnsClientBuilder().withEmailKeyAuth("a@b.de", null)); + } + + @Test + void testBuildWithoutAuthFails() { + assertThrows(IllegalStateException.class, () -> new CfDnsClientBuilder().build()); + assertThrows(IllegalStateException.class, + () -> new CfDnsClientBuilder().withBaseUrl("https://api.example.com").build()); + } } diff --git a/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java b/src/test/java/codes/thischwa/cf/CfDnsClientMockTest.java index bc5b7f9..ce60241 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; @@ -118,6 +119,34 @@ class CfDnsClientMockTest { assertEquals("test.com", zones.get(1).getName()); } + @Test + void testZoneList_WithPagingEnforcesApiLimits() throws Exception { + ZoneMultipleResponse mockResponse = new ZoneMultipleResponse(); + mockResponse.setResult(List.of()); + mockResponse.setResponseResultInfo(createSuccessResultInfo()); + + CfDnsClient spyClient = spy(client); + doReturn(mockResponse).when(spyClient).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + + spyClient.zoneList(PagingRequest.of(1, 5)); + spyClient.zoneList(PagingRequest.of(1, 50)); + + verify(spyClient).getRequest(eq("/zones?page=1&per_page=5"), eq(ZoneMultipleResponse.class)); + verify(spyClient).getRequest(eq("/zones?page=1&per_page=50"), eq(ZoneMultipleResponse.class)); + } + + @Test + void testZoneList_WithPagingRejectsOutOfRangePageSizes() throws Exception { + CfDnsClient spyClient = spy(client); + + assertThrows(IllegalArgumentException.class, + () -> spyClient.zoneList(PagingRequest.of(1, 4))); + assertThrows(IllegalArgumentException.class, + () -> spyClient.zoneList(PagingRequest.of(1, 51))); + + verify(spyClient, never()).getRequest(anyString(), eq(ZoneMultipleResponse.class)); + } + @Test void testZoneGet() throws Exception { // Create mock zone response @@ -218,7 +247,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 +268,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 +289,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 +389,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 +425,447 @@ 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&order=name&direction=asc&page=%d&per_page=" + CfDnsClient.MAX_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&order=name&direction=asc&page=%d&per_page=" + + CfDnsClient.MAX_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&order=name&direction=asc&page=1&per_page=" + + CfDnsClient.MAX_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()); + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?order=name&direction=asc&page=1&per_page=" + PagingRequest.MAX_PER_PAGE), + eq(RecordMultipleResponse.class)); + } + + @Test + void testRecordList_ExplicitPagingRequestIsPreserved() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + spyClient.recordList(createTestZone(), PagingRequest.of(2, 42)); + + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?order=name&direction=asc&page=2&per_page=42"), + eq(RecordMultipleResponse.class)); + } + + @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&order=name&direction=asc&page=1&per_page=" + + CfDnsClient.MAX_RECORDS_PER_PAGE), eq(RecordMultipleResponse.class)); + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?name=www.example.com&type=TXT&order=name&direction=asc&page=1&per_page=" + + CfDnsClient.MAX_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?order=name&direction=asc&page=1&per_page=" + + CfDnsClient.MAX_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("priority", 10, "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()); + } + + @Test + void testInvalidSubdomainIsRejectedBeforeRequest() throws Exception { + CfDnsClient spyClient = spy(client); + ZoneEntity zone = createTestZone(); + for (String sub : List.of("; rm -rf /", "| cat /etc/passwd", "`shutdown -h now`", + "", "\"quoted\"", "a b", "x?y", "x#y", "x&y", "x\ty", " ", "")) { + assertThrows(IllegalArgumentException.class, () -> spyClient.recordListBySubdomain(zone, sub), sub); + assertThrows(IllegalArgumentException.class, + () -> spyClient.recordCreateSubdomain(zone, sub, 60, RecordType.A, "1.2.3.4"), sub); + } + assertThrows(IllegalArgumentException.class, () -> spyClient.recordListBySubdomain(zone, null)); + assertThrows(IllegalArgumentException.class, () -> spyClient.zoneGet("example.com&account.id=1")); + assertThrows(IllegalArgumentException.class, () -> spyClient.zoneGet(" ")); + verify(spyClient, never()).getRequest(anyString(), any()); + verify(spyClient, never()).postRequest(anyString(), any(), any()); + } + + @Test + void testUnusualButValidSubdomainIsEncoded() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(), new ResultInfo(0))) + .when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class)); + + spyClient.recordListBySubdomain(createTestZone(), "$(reboot)"); + spyClient.recordListBySubdomain(createTestZone(), "0/26"); + + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?name=%24%28reboot%29.example.com&order=name&direction=asc&page=1&per_page=" + CfDnsClient.MAX_RECORDS_PER_PAGE), + eq(RecordMultipleResponse.class)); + verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + + "/dns_records?name=0%2F26.example.com&order=name&direction=asc&page=1&per_page=" + CfDnsClient.MAX_RECORDS_PER_PAGE), + eq(RecordMultipleResponse.class)); + } + + @Test + void testRecordIdPathTraversalIsRejected() throws Exception { + CfDnsClient spyClient = spy(client); + ZoneEntity zone = createTestZone(); + assertThrows(IllegalArgumentException.class, () -> spyClient.recordDelete(zone, "../..")); + RecordEntity rec = RecordEntity.build("../..", "1.2.3.4"); + assertThrows(IllegalArgumentException.class, () -> spyClient.recordUpdate(zone, rec)); + ZoneEntity badZone = zone("../../accounts", "example.com"); + assertThrows(IllegalArgumentException.class, () -> spyClient.recordList(badZone)); + verify(spyClient, never()).deleteRequest(anyString(), any()); + verify(spyClient, never()).patchRequest(anyString(), any(), any()); + verify(spyClient, never()).getRequest(anyString(), any()); + } + + private static RecordEntity rec(String id, String name) { + RecordEntity rec = RecordEntity.build(name, RecordType.A, 60, "1.1.1.1"); + rec.setId(id); + return rec; + } + + private static String recordsPage(int page) { + return "/zones/" + TEST_ZONE_ID + "/dns_records?order=name&direction=asc&page=" + page + + "&per_page=" + PagingRequest.MAX_PER_PAGE; + } + + @Test + void testRecordList_InconsistentPagesAreFetchedAgain() throws Exception { + CfDnsClient spyClient = spy(client); + // 1st attempt: page 2 repeats a record of page 1 (unstable order), so record c is missing + doReturn(recordResponse(List.of(rec("a", "a.example.com"), rec("b", "b.example.com")), + new ResultInfo(1, 2, 2, 2, 3))) + .when(spyClient).getRequest(eq(recordsPage(1)), eq(RecordMultipleResponse.class)); + doReturn(recordResponse(List.of(rec("b", "b.example.com")), new ResultInfo(2, 2, 2, 1, 3)), + recordResponse(List.of(rec("c", "c.example.com")), new ResultInfo(2, 2, 2, 1, 3))) + .when(spyClient).getRequest(eq(recordsPage(2)), eq(RecordMultipleResponse.class)); + + List records = spyClient.recordList(createTestZone()); + + assertEquals(List.of("a", "b", "c"), records.stream().map(RecordEntity::getId).toList()); + verify(spyClient, times(2)).getRequest(eq(recordsPage(1)), eq(RecordMultipleResponse.class)); + verify(spyClient, times(2)).getRequest(eq(recordsPage(2)), eq(RecordMultipleResponse.class)); + } + + @Test + void testRecordList_PersistentlyInconsistentPagesReturnDeduplicatedResult() throws Exception { + CfDnsClient spyClient = spy(client); + doReturn(recordResponse(List.of(rec("a", "a.example.com"), rec("b", "b.example.com")), + new ResultInfo(1, 2, 2, 2, 3))) + .when(spyClient).getRequest(eq(recordsPage(1)), eq(RecordMultipleResponse.class)); + doReturn(recordResponse(List.of(rec("b", "b.example.com")), new ResultInfo(2, 2, 2, 1, 3))) + .when(spyClient).getRequest(eq(recordsPage(2)), eq(RecordMultipleResponse.class)); + + List records = spyClient.recordList(createTestZone()); + + // no duplicates, after 3 attempts the incomplete result is returned + assertEquals(List.of("a", "b"), records.stream().map(RecordEntity::getId).toList()); + verify(spyClient, times(3)).getRequest(eq(recordsPage(1)), eq(RecordMultipleResponse.class)); + } } diff --git a/src/test/java/codes/thischwa/cf/CfRequestTest.java b/src/test/java/codes/thischwa/cf/CfRequestTest.java index 14aa061..61fb4b4 100644 --- a/src/test/java/codes/thischwa/cf/CfRequestTest.java +++ b/src/test/java/codes/thischwa/cf/CfRequestTest.java @@ -55,4 +55,32 @@ public class CfRequestTest { IllegalArgumentException.class, () -> CfRequest.RECORD_UPDATE.buildPath("zone123")); } + + @Test + public void testQueryValueIsUrlEncoded() { + assertEquals("/zones?name=example.com%26account.id%3D1", + CfRequest.ZONE_INFO.buildPath("example.com&account.id=1")); + assertEquals("/zones/zone123/dns_records?name=..%2F..%2Fx.example.com", + CfRequest.RECORD_LIST_NAME.buildPath("zone123", "../../x.example.com")); + assertEquals("/zones/zone123/dns_records?name=%24%28reboot%29.example.com", + CfRequest.RECORD_LIST_NAME.buildPath("zone123", "$(reboot).example.com")); + assertEquals("/zones/zone123/dns_records?name=%F0%9F%A5%B7.example.com", + CfRequest.RECORD_LIST_NAME.buildPath("zone123", "\uD83E\uDD77.example.com")); + assertEquals("/zones/zone123/dns_records?name=*.example.com", + CfRequest.RECORD_LIST_NAME.buildPath("zone123", "*.example.com")); + } + + @Test + public void testInvalidIdentifiersAreRejected() { + for (String id : new String[] {"..", "../..", "a/b", "a b", "id?x=1", "id#x", "", "%2e%2e", + "a".repeat(65)}) { + assertThrows(IllegalArgumentException.class, + () -> CfRequest.RECORD_DELETE.buildPath("zone123", id), "id: " + id); + assertThrows(IllegalArgumentException.class, + () -> CfRequest.RECORD_LIST.buildPath(id), "zone id: " + id); + } + assertThrows(IllegalArgumentException.class, () -> CfRequest.RECORD_LIST.buildPath((Object) null)); + assertEquals("/zones/0123456789abcdef0123456789abcdef/dns_records", + CfRequest.RECORD_LIST.buildPath("0123456789abcdef0123456789abcdef")); + } } 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/PagingRequestTest.java b/src/test/java/codes/thischwa/cf/model/PagingRequestTest.java index f399942..0726cf2 100644 --- a/src/test/java/codes/thischwa/cf/model/PagingRequestTest.java +++ b/src/test/java/codes/thischwa/cf/model/PagingRequestTest.java @@ -9,7 +9,26 @@ public class PagingRequestTest { @Test void testBuildPath() { String result = PagingRequest.defaultPaging().addQueryString("/zones"); - assertEquals("/zones?page=1&per_page=1000", result); + assertEquals("/zones?page=1&per_page=50", result); + } + + @Test + void testPagingRequestBoundaries() { + assertDoesNotThrow(() -> PagingRequest.of(1, 1)); + assertDoesNotThrow(() -> PagingRequest.of(1, 5_000_000)); + assertThrows(IllegalArgumentException.class, () -> PagingRequest.of(0, 1)); + assertThrows(IllegalArgumentException.class, () -> PagingRequest.of(1, 0)); + assertThrows(IllegalArgumentException.class, () -> PagingRequest.of(1, 5_000_001)); + } + + @Test + void testSettersValidatePagingValues() { + PagingRequest request = PagingRequest.of(1, 50); + + assertThrows(IllegalArgumentException.class, () -> request.setPage(0)); + assertThrows(IllegalArgumentException.class, () -> request.setPerPage(5_000_001)); + assertEquals(1, request.getPage()); + assertEquals(50, request.getPerPage()); } @Test 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);