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:
1 parent
4b560141a1
commit
732f92ee78
22 files changed
+1256
-336
No files matched your search
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user