AI code review: fix bugs, rename sld to subdomain, improve usability (#2)

- bug fixes: API errors are no longer wrapped into "Unexpected error!",
  zoneGet no longer crashes on unknown zones, getSubdomain handles apex
  and multi-level names, batch operations send the full record name,
  list methods fetch all pages, recordDelete handles empty results
- rename "sld" to "subdomain": getSubdomain(), recordCreateSubdomain(),
  old methods deprecated; "@" (CfDnsClient.APEX) addresses the apex
- one shared HTTP client with connection pooling, CfDnsClient
  implements AutoCloseable
- CloudflareApiException provides HTTP status code and Cloudflare
  errors, HTTP 404 throws CloudflareNotFoundException
- RecordEntity supports priority, data, comment and tags
- recordCreate/recordUpdate send only writable attributes and don't
  modify the given record
- breaking: recordList overloads replaced by recordListBySubdomain and
  recordListByType, timestamps are java.time.Instant
- single record type is filtered server-side (?type=)
- tests, README and changelog updated

refs #2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
thischwaandClaude Opus 5.5 committed 2026-11-03 15:44:25 +01:00
1 parent 4b560141a1
commit 732f92ee78
22 files changed
+1256 -336

No files matched your search

+75 -41
View File
@@ -62,6 +62,15 @@ CfDnsClient cfDnsClient = new CfDnsClientBuilder()
.build();
```
The client is thread-safe and should be reused, it holds a pool of HTTP connections.
`CfDnsClient` implements `AutoCloseable`, call `close()` (or use try-with-resources) to release the connections:
```java
try (CfDnsClient cfDnsClient = new CfDnsClientBuilder().withApiTokenAuth("your-api-token").build()) {
// ...
}
```
### `zoneList`
Retrieve all zones within the Cloudflare account.
@@ -100,49 +109,53 @@ System.out.println("Zone ID: " + zone.getId());
Retrieve records for a given zone. There are two variants:
#### List by SLD
Retrieve all records for a specific second-level domain (SLD) under a given zone.
#### List by subdomain (`recordListBySubdomain`)
Retrieve all records for a specific subdomain under a given zone, optionally filtered by record types.
- **Parameters**:
- `ZoneEntity zone` - The zone object.
- `String sld` - Second-level domain (e.g., "www" in "www.example.com").
- `String subdomain` - The subdomain relative to the zone (e.g., "www" in "www.example.com"
or "my.sub" in "my.sub.example.com"). Use `CfDnsClient.APEX` (`"@"`) for the zone apex.
- `RecordType... types` - Optional record types to filter by. If not specified, returns all record types.
- **Returns**: A list of `RecordEntity` objects.
```java
List<RecordEntity> 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<RecordEntity> wwwRecords = cfDnsClient.recordListBySubdomain(zone, "www");
// Get only A records for a specific subdomain
List<RecordEntity> wwwARecords = cfDnsClient.recordListBySubdomain(zone, "www", RecordType.A);
// Get the records of the zone apex (e.g. "example.com")
List<RecordEntity> 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<RecordEntity> allSldRecords = cfDnsClient.recordList(zone, "www");
// Get only A and AAAA records of a zone
List<RecordEntity> ipZoneRecords = cfDnsClient.recordListByType(zone, RecordType.A, RecordType.AAAA);
```
// Get only A records for a specific SLD
List<RecordEntity> 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<RecordEntity> allZoneRecords = cfDnsClient.recordList(zone);
// Get only A and AAAA records of a zone
List<RecordEntity> ipZoneRecords = cfDnsClient.recordList(zone, RecordType.A, RecordType.AAAA);
// Get the records of a zone page by page (page 2, 100 records per page)
List<RecordEntity> pagedRecords = cfDnsClient.recordList(zone, PagingRequest.of(2, 100));
```
Without a `PagingRequest`, up to 1000 records are fetched in a single request.
Without a `PagingRequest`, all pages are fetched and the complete result is returned.
With a `PagingRequest`, exactly the requested page is returned.
`RecordEntity#getSubdomain()` returns the record name relative to its zone, e.g. `my.sub` for
`my.sub.example.com` and `"@"` for the zone apex. The timestamps `getCreatedOn()` and `getModifiedOn()`
are of type `java.time.Instant` (UTC).
#### Group by FQDN
@@ -154,20 +167,20 @@ Map<String, List<RecordEntity>> byFqdn = CfDnsClient.groupRecordsByFqdn(cfDnsCli
---
### `recordCreateSld` / `recordCreate`
### `recordCreateSubdomain` / `recordCreate`
Create a new DNS record in a specific zone.
- **Parameters**:
- `ZoneEntity zone` - The DNS zone object.
- `String sld` - The second-level domain of the new record (e.g., "api" in "api.example.com").
- `String subdomain` - The subdomain of the new record relative to the zone (e.g., "api" in "api.example.com").
- `int ttl` - The time-to-live in seconds of the new record.
- `RecordType type` - The record type (e.g., A, AAAA, CNAME).
- `String content` - The content of the record (e.g., the IP address of an A record).
- **Returns**: The created `RecordEntity`.
```java
RecordEntity created = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.1");
RecordEntity created = cfDnsClient.recordCreateSubdomain(zone, "api", 60, RecordType.A, "192.168.1.1");
System.out.println("Created Record ID: " + created.getId());
```
@@ -178,11 +191,28 @@ cfDnsClient.recordCreate(zone, "api.example.com", 60, RecordType.A, "192.168.1.1
cfDnsClient.recordCreate(zone, RecordEntity.build("api.example.com", RecordType.A, 60, "192.168.1.1"));
```
Records which need more than a content, like MX, SRV or CAA records, can be created from a `RecordEntity`.
Besides `priority` and `data`, the attributes `proxied`, `comment` and `tags` are supported:
```java
// MX record with priority
RecordEntity mx = RecordEntity.build("example.com", RecordType.MX, 3600, "mail.example.com");
mx.setPriority(10);
cfDnsClient.recordCreate(zone, mx);
// SRV record with structured data (keys as in the Cloudflare API)
RecordEntity srv = RecordEntity.build("_sip._tcp.example.com", RecordType.SRV, 3600, null);
srv.setPriority(10);
srv.setData(Map.of("weight", 5, "port", 5060, "target", "sip.example.com"));
cfDnsClient.recordCreate(zone, srv);
```
---
### `recordUpdate`
Update an existing DNS record.
Update an existing DNS record (partial update: attributes which are `null` remain unchanged).
Read-only attributes like timestamps are ignored, the given `RecordEntity` isn't modified.
- **Parameters**:
- `ZoneEntity zone` - The zone that contains the record.
@@ -223,7 +253,7 @@ Delete the DNS records of the given types if they exist.
- **Parameters**:
- `ZoneEntity zone` - Target zone.
- `String sld` - Second-level domain.
- `String subdomain` - The subdomain relative to the zone.
- `RecordType... types` - One or more record types.
```java
@@ -266,8 +296,8 @@ Partially update existing records. **Record IDs are required** - fetch them firs
```java
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToUpdate = new ArrayList<>();
recordsToUpdate.add(cfDnsClient.recordList(zone, "api",RecordType.A).get(0));
recordsToUpdate.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0));
recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "api",RecordType.A).get(0));
recordsToUpdate.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
// Step 2: Modify only the fields you want to update
recordsToUpdate.forEach(record ->record.setContent("192.168.2.10"));
@@ -284,8 +314,8 @@ Fully replace existing records. **Record IDs are required** - fetch them first:
```java
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToReplace = new ArrayList<>();
recordsToReplace.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0));
recordsToReplace.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0));
recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0));
recordsToReplace.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
// Step 2: Modify all fields as needed (full replacement)
recordsToReplace.get(0).setContent("192.168.3.10");
@@ -305,8 +335,8 @@ Delete existing records. **Record IDs are required** - fetch them first:
```java
// Step 1: Fetch existing records to get their IDs
List<RecordEntity> recordsToDelete = new ArrayList<>();
recordsToDelete.add(cfDnsClient.recordList(zone, "cdn",RecordType.A).get(0));
recordsToDelete.add(cfDnsClient.recordList(zone, "mail",RecordType.A).get(0));
recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "cdn",RecordType.A).get(0));
recordsToDelete.add(cfDnsClient.recordListBySubdomain(zone, "mail",RecordType.A).get(0));
// Step 2: Send batch delete request
BatchEntry result = cfDnsClient.recordBatch(zone, null, null, null, recordsToDelete);
@@ -325,12 +355,12 @@ List<RecordEntity> newRecords = Arrays.asList(
// Fetch existing records for update/delete (IDs required)
List<RecordEntity> 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<RecordEntity> recordsToDelete = Arrays.asList(
cfDnsClient.recordList(zone, "old-api", RecordType.A).get(0)
cfDnsClient.recordListBySubdomain(zone, "old-api", RecordType.A).get(0)
);
// Execute all operations in a single batch request
@@ -425,7 +455,10 @@ client.zone("example.com")
The `CfDnsClient` provides internal error-handling mechanisms through exceptions. For example:
- `CloudflareApiException` is thrown for errors during API communication or invalid responses.
- `CloudflareNotFoundException` is thrown when the requested resource (single or multiple) is not found, if enabled via the `emptyResultThrowsException` flag during initialization. **Default is `false`**, meaning empty results will be returned without throwing an exception.
`getStatusCode()` returns the HTTP status code (or `CloudflareApiException.NO_STATUS_CODE` if there was no response)
and `getErrors()` the error codes and messages reported by Cloudflare.
- `CloudflareNotFoundException` is thrown if Cloudflare responds with HTTP status 404 (e.g. deleting a non-existing record).
- `CloudflareNotFoundException` is also thrown when the requested resource (single or multiple) is not found, if enabled via the `emptyResultThrowsException` flag during initialization. **Default is `false`**, meaning empty results will be returned without throwing an exception.
To enable exception throwing for empty results:
@@ -440,13 +473,14 @@ CfDnsClient client = new CfDnsClientBuilder()
```java
try {
List<RecordEntity> records = cfDnsClient.recordList(zone, "www", RecordType.A);
List<RecordEntity> 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;
}
}