Align pagination with Cloudflare API limits Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
1 parent
7aab2e9610
commit
369c584f5f
11 files changed
+185
-62
No files matched your search
@@ -12,3 +12,4 @@
|
|||||||
cf.yml
|
cf.yml
|
||||||
/docs/apidocs/javadoc.sh
|
/docs/apidocs/javadoc.sh
|
||||||
/.claude/settings.local.json
|
/.claude/settings.local.json
|
||||||
|
/.junie/
|
||||||
@@ -95,12 +95,17 @@ List<ZoneEntity> zones = cfDnsClient.zoneList();
|
|||||||
zones.forEach(zone -> System.out.println("Zone: " + zone.getName()));
|
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
|
```java
|
||||||
List<ZoneEntity> zones = cfDnsClient.zoneList(PagingRequest.of(1, 50)); // page 1, 50 zones per page
|
List<ZoneEntity> 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`
|
### `zoneGet`
|
||||||
@@ -163,7 +168,8 @@ List<RecordEntity> allZoneRecords = cfDnsClient.recordList(zone);
|
|||||||
List<RecordEntity> pagedRecords = cfDnsClient.recordList(zone, PagingRequest.of(2, 100));
|
List<RecordEntity> pagedRecords = cfDnsClient.recordList(zone, PagingRequest.of(2, 100));
|
||||||
```
|
```
|
||||||
|
|
||||||
Without a `PagingRequest`, all pages are fetched and the complete result is returned.
|
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.
|
With a `PagingRequest`, exactly the requested page is returned.
|
||||||
|
|
||||||
`RecordEntity#getSubdomain()` returns the record name relative to its zone, e.g. `my.sub` for
|
`RecordEntity#getSubdomain()` returns the record name relative to its zone, e.g. `my.sub` for
|
||||||
@@ -273,6 +279,8 @@ cfDnsClient.recordDeleteTypeIfExists(zone, "api", RecordType.A, RecordType.AAAA)
|
|||||||
System.out.println("Deletion attempt completed.");
|
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
|
### Batch Operations
|
||||||
|
|
||||||
Process multiple DNS record operations (POST, PUT, PATCH, DELETE) in a single batch request.
|
Process multiple DNS record operations (POST, PUT, PATCH, DELETE) in a single batch request.
|
||||||
@@ -425,6 +433,8 @@ client.zone("example.com")
|
|||||||
.delete(RecordType.A, RecordType.AAAA);
|
.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
|
### Advantages of Fluent API
|
||||||
|
|
||||||
- **More Readable**: The chain of method calls reads like natural language
|
- **More Readable**: The chain of method calls reads like natural language
|
||||||
|
|||||||
+5
-6
@@ -6,6 +6,8 @@
|
|||||||
- `recordList(zone, String subdomain, RecordType... types)` and `recordList(zone, String subdomain)` → `recordListBySubdomain(zone, subdomain, types...)`
|
- `recordList(zone, String subdomain, RecordType... types)` and `recordList(zone, String subdomain)` → `recordListBySubdomain(zone, subdomain, types...)`
|
||||||
- `recordList(zone, RecordType... types)` → `recordListByType(zone, types...)`
|
- `recordList(zone, RecordType... types)` → `recordListByType(zone, types...)`
|
||||||
- `recordList(zone)` and `recordList(zone, PagingRequest)` remain unchanged
|
- `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
|
- `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`
|
- `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
|
- zone names and subdomains with whitespace, control characters or `\ ? # & ; | < > " ' `` ` `` are rejected with an `IllegalArgumentException`, zone and record IDs must be alphanumeric
|
||||||
@@ -23,16 +25,13 @@
|
|||||||
- filtering by exactly one record type is done by Cloudflare (`?type=`), unknown record types in responses don't break the client-side filter anymore
|
- 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 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
|
- 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 log and exception messages (e.g. "Invalid record type")
|
||||||
- fixed "getRecord" wording in javadoc, 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()`
|
||||||
- **Deprecation**: the misleading term "sld" was renamed to "subdomain", the old methods will be removed in a future release:
|
|
||||||
- `RecordEntity#getSld()` → `RecordEntity#getSubdomain()`
|
|
||||||
- `CfDnsClient#recordCreateSld(...)` → `CfDnsClient#recordCreateSubdomain(...)`
|
|
||||||
- `getSubdomain()` returns `"@"` for the zone apex; `CfDnsClient.APEX` can be used to address the zone apex
|
- `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: 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: `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: `getSubdomain()` failed for apex records and records with multi-level subdomains, batch operations now send the full record name
|
||||||
- fixed: `zoneList()` and `recordList(...)` without `PagingRequest` returned only the first page, now all pages are fetched
|
- fixed: `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: 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
|
- fixed: `recordDelete` threw a `NullPointerException` for an empty result
|
||||||
- 0.5.0:
|
- 0.5.0:
|
||||||
|
|||||||
@@ -88,14 +88,16 @@ import org.jetbrains.annotations.Nullable;
|
|||||||
public class CfDnsClient extends CfBasicHttpClient {
|
public class CfDnsClient extends CfBasicHttpClient {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Page size used when fetching all zones. Cloudflare allows max. 50 zones per page.
|
* Page size used when fetching all zones. Cloudflare allows 5 to 50 zones per page.
|
||||||
*/
|
*/
|
||||||
static final int ZONES_PER_PAGE = 50;
|
static final int ZONES_PER_PAGE = 50;
|
||||||
|
|
||||||
|
private static final int MIN_ZONES_PER_PAGE = 5;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Page size used when fetching all DNS records.
|
* Page size used when fetching all DNS records.
|
||||||
*/
|
*/
|
||||||
static final int RECORDS_PER_PAGE = 1000;
|
static final int MAX_RECORDS_PER_PAGE = 1000;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Sort order for listing DNS records. Cloudflare doesn't guarantee a stable order without it,
|
* Sort order for listing DNS records. Cloudflare doesn't guarantee a stable order without it,
|
||||||
@@ -129,7 +131,7 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
* @param auth The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
|
* @param auth The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
|
||||||
*/
|
*/
|
||||||
CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfDnsClientBuilder.CfAuth auth) {
|
CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfDnsClientBuilder.CfAuth auth) {
|
||||||
this(emptyResultThrowsException, baseUrl, auth, RECORDS_PER_PAGE);
|
this(emptyResultThrowsException, baseUrl, auth, MAX_RECORDS_PER_PAGE);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -238,14 +240,21 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Retrieves a single page of 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
|
* @param pagingRequest the pagination request object containing parameters for paging and
|
||||||
* filtering zone data
|
* filtering zone data
|
||||||
* @return a list of {@code ZoneEntity} objects representing the DNS zones retrieved from the API
|
* @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
|
* @throws CloudflareApiException if there is an error during the API request or response
|
||||||
* processing
|
* processing
|
||||||
|
* @throws IllegalArgumentException if the page size is outside the range 5 to 50
|
||||||
*/
|
*/
|
||||||
public List<ZoneEntity> zoneList(PagingRequest pagingRequest) throws CloudflareApiException {
|
public List<ZoneEntity> 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());
|
String endpoint = pagingRequest.addQueryString(CfRequest.ZONE_LIST.buildPath());
|
||||||
ZoneMultipleResponse response = getRequest(endpoint, ZoneMultipleResponse.class);
|
ZoneMultipleResponse response = getRequest(endpoint, ZoneMultipleResponse.class);
|
||||||
checkResponse(response);
|
checkResponse(response);
|
||||||
@@ -290,7 +299,8 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
*
|
*
|
||||||
* @param zone The zone entity containing information about the target zone.
|
* @param zone The zone entity containing information about the target zone.
|
||||||
* @param pagingRequest The paging request containing parameters such as page size and number.
|
* @param pagingRequest The paging request containing parameters such as page size and number.
|
||||||
* If {@code null}, all pages are fetched.
|
* 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.
|
* @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.
|
* @throws CloudflareApiException If an error occurs during the API request or response processing.
|
||||||
*/
|
*/
|
||||||
@@ -299,7 +309,7 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
String path = appendQuery(CfRequest.RECORD_LIST.buildPath(zone.getId()), RECORD_ORDER);
|
String path = appendQuery(CfRequest.RECORD_LIST.buildPath(zone.getId()), RECORD_ORDER);
|
||||||
if (pagingRequest == null) {
|
if (pagingRequest == null) {
|
||||||
return filterAndSetZoneRecords(zone, null,
|
return filterAndSetZoneRecords(zone, null,
|
||||||
getAllPages(path, RecordMultipleResponse.class, recordsPerPage));
|
getAllPages(path, RecordMultipleResponse.class, PagingRequest.MAX_PER_PAGE));
|
||||||
}
|
}
|
||||||
RecordMultipleResponse resp = getRequest(pagingRequest.addQueryString(path), RecordMultipleResponse.class);
|
RecordMultipleResponse resp = getRequest(pagingRequest.addQueryString(path), RecordMultipleResponse.class);
|
||||||
checkResponse(resp);
|
checkResponse(resp);
|
||||||
@@ -371,26 +381,6 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
return recordCreate(zone, fqdn, ttl, type, content);
|
return recordCreate(zone, fqdn, ttl, type, content);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Creates a new DNS record for a given subdomain within the specified zone.
|
|
||||||
*
|
|
||||||
* @param zone The ZoneEntity representing the DNS zone where the record is to be created.
|
|
||||||
* @param subdomain The subdomain relative to the zone.
|
|
||||||
* @param ttl The time-to-live (TTL) value for the DNS record in seconds.
|
|
||||||
* @param type The RecordType specifying the type of the DNS record.
|
|
||||||
* @param content The content of the DNS record.
|
|
||||||
* @return The created RecordEntity object containing details of the newly created DNS record.
|
|
||||||
* @throws CloudflareApiException If an error occurs while communicating with the Cloudflare API
|
|
||||||
* or creating the record.
|
|
||||||
* @deprecated The name was misleading, use
|
|
||||||
* {@link #recordCreateSubdomain(ZoneEntity, String, int, RecordType, String)} instead.
|
|
||||||
*/
|
|
||||||
@Deprecated(since = "0.6.0", forRemoval = true)
|
|
||||||
public RecordEntity recordCreateSld(ZoneEntity zone, String subdomain, int ttl, RecordType type,
|
|
||||||
String content) throws CloudflareApiException {
|
|
||||||
return recordCreateSubdomain(zone, subdomain, ttl, type, content);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates a DNS record in the specified DNS zone with the provided details.
|
* Creates a DNS record in the specified DNS zone with the provided details.
|
||||||
*
|
*
|
||||||
@@ -496,13 +486,16 @@ public class CfDnsClient extends CfBasicHttpClient {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Deletes DNS records of a specific type within a given zone if they exist. If no record of the
|
* Attempts to delete DNS records of the specified types within a given zone. If no record types
|
||||||
* specified type exists, it logs this occurrence without throwing an exception.
|
* 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 zone The DNS zone entity in which the record exists.
|
||||||
* @param subdomain The subdomain relative to the zone for which the records are being checked.
|
* @param subdomain The subdomain relative to the zone for which the records are being checked.
|
||||||
* @param recordTypes The types of DNS records that should be deleted if they exist.
|
* @param recordTypes The DNS record types to delete; if empty or {@code null}, all types are selected.
|
||||||
* @throws CloudflareApiException If an error occurs during API communication.
|
* @throws CloudflareApiException If an error occurs while retrieving the records to delete.
|
||||||
* @throws IllegalArgumentException if the subdomain is blank or contains invalid characters
|
* @throws IllegalArgumentException if the subdomain is blank or contains invalid characters
|
||||||
*/
|
*/
|
||||||
public void recordDeleteTypeIfExists(ZoneEntity zone, String subdomain, RecordType... recordTypes)
|
public void recordDeleteTypeIfExists(ZoneEntity zone, String subdomain, RecordType... recordTypes)
|
||||||
|
|||||||
@@ -195,7 +195,7 @@ public class CfDnsClientBuilder {
|
|||||||
"No authentication configured, use withApiTokenAuth(...) or withEmailKeyAuth(...)");
|
"No authentication configured, use withApiTokenAuth(...) or withEmailKeyAuth(...)");
|
||||||
}
|
}
|
||||||
String url = baseUrl == null ? DEFAULT_BASEURL : baseUrl;
|
String url = baseUrl == null ? DEFAULT_BASEURL : baseUrl;
|
||||||
return new CfDnsClient(emptyResultThrowsException, url, auth, CfDnsClient.RECORDS_PER_PAGE,
|
return new CfDnsClient(emptyResultThrowsException, url, auth, CfDnsClient.MAX_RECORDS_PER_PAGE,
|
||||||
connectTimeout, responseTimeout);
|
connectTimeout, responseTimeout);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -40,10 +40,15 @@ public interface RecordOperations {
|
|||||||
RecordEntity update(String newContent) throws CloudflareApiException;
|
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
|
* @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;
|
void delete(RecordType... types) throws CloudflareApiException;
|
||||||
}
|
}
|
||||||
@@ -21,6 +21,11 @@ public interface ZoneOperations {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Selects a record with specific types within the zone for further operations.
|
* Selects a record with specific types within the zone for further operations.
|
||||||
|
* <p>
|
||||||
|
* 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 subdomain the subdomain relative to the zone (e.g. "www"), or "@" for the zone apex
|
* @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
|
* @param types optional DNS record types to filter by
|
||||||
|
|||||||
@@ -7,7 +7,9 @@ import lombok.Data;
|
|||||||
* Represents a request model for paginated data.
|
* Represents a request model for paginated data.
|
||||||
*
|
*
|
||||||
* <p>This class encapsulates the page number and the number of items per page for a paginated
|
* <p>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.
|
||||||
*
|
*
|
||||||
* <p>Key functionalities:
|
* <p>Key functionalities:
|
||||||
*
|
*
|
||||||
@@ -22,52 +24,83 @@ import lombok.Data;
|
|||||||
@Data
|
@Data
|
||||||
public class PagingRequest {
|
public class PagingRequest {
|
||||||
/**
|
/**
|
||||||
* Default page size for retrieving all records in a single request.
|
* Default page size for a single request, which is within the limits for zones and DNS records.
|
||||||
* Set to a very high value to effectively disable pagination when fetching all 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 page;
|
||||||
private int perPage;
|
private int perPage;
|
||||||
|
|
||||||
PagingRequest(int page, int perPage) {
|
PagingRequest(int page, int perPage) {
|
||||||
this.page = page;
|
this.page = validatePage(page);
|
||||||
this.perPage = perPage;
|
this.perPage = validatePerPage(perPage);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates a new {@code PagingRequest} instance with the specified page number and items per page.
|
* 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 page the page number to be requested
|
||||||
* @param perPage the number of items to be included per page
|
* @param perPage the number of items to be included per page
|
||||||
* @return a new {@code PagingRequest} instance with the provided parameters
|
* @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) {
|
public static PagingRequest of(int page, int perPage) {
|
||||||
return new PagingRequest(page, perPage);
|
return new PagingRequest(page, perPage);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates a default {@code PagingRequest} instance with a page number set to 1 and a high number
|
* Creates a default {@code PagingRequest} instance for page 1 with 50 items per page. This is a
|
||||||
* of items per page to accommodate large dataset requests and effectively retrieve all records.
|
* request for one page; it does not fetch additional pages.
|
||||||
*
|
*
|
||||||
* @return a default {@code PagingRequest} instance with predefined pagination parameters
|
* @return a default {@code PagingRequest} instance with predefined pagination parameters
|
||||||
*/
|
*/
|
||||||
public static PagingRequest defaultPaging() {
|
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.
|
* Retrieves the pagination parameters in a key-value map format.
|
||||||
*
|
*
|
||||||
* @return a map containing the pagination parameters, where the key "page" indicates the current
|
* @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<String, String> getPagingParams() {
|
public Map<String, String> getPagingParams() {
|
||||||
return Map.of("page", String.valueOf(page), "perPage", String.valueOf(perPage));
|
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
|
* @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
|
* @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;
|
String qs = "page=" + page + "&per_page=" + perPage;
|
||||||
return add ? "&" + qs : "?" + qs;
|
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;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
@@ -109,7 +109,7 @@ public class CfClientTest {
|
|||||||
assertFalse(zones.isEmpty());
|
assertFalse(zones.isEmpty());
|
||||||
assertEquals(ZONE_STR, zones.get(0).getName());
|
assertEquals(ZONE_STR, zones.get(0).getName());
|
||||||
|
|
||||||
zones = client.zoneList(PagingRequest.of(1, 100));
|
zones = client.zoneList(PagingRequest.of(1, 50));
|
||||||
assertNotNull(zones);
|
assertNotNull(zones);
|
||||||
assertFalse(zones.isEmpty());
|
assertFalse(zones.isEmpty());
|
||||||
assertEquals(ZONE_STR, zones.get(0).getName());
|
assertEquals(ZONE_STR, zones.get(0).getName());
|
||||||
|
|||||||
@@ -119,6 +119,34 @@ class CfDnsClientMockTest {
|
|||||||
assertEquals("test.com", zones.get(1).getName());
|
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
|
@Test
|
||||||
void testZoneGet() throws Exception {
|
void testZoneGet() throws Exception {
|
||||||
// Create mock zone response
|
// Create mock zone response
|
||||||
@@ -471,7 +499,7 @@ class CfDnsClientMockTest {
|
|||||||
@Test
|
@Test
|
||||||
void testRecordListByType_FetchesAllPages() throws Exception {
|
void testRecordListByType_FetchesAllPages() throws Exception {
|
||||||
ZoneEntity zone = createTestZone();
|
ZoneEntity zone = createTestZone();
|
||||||
String base = "/zones/" + TEST_ZONE_ID + "/dns_records?type=A&order=name&direction=asc&page=%d&per_page=" + CfDnsClient.RECORDS_PER_PAGE;
|
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);
|
CfDnsClient spyClient = spy(client);
|
||||||
doReturn(recordResponse(List.of(RecordEntity.build("a.example.com", RecordType.A, 60, "1.1.1.1")),
|
doReturn(recordResponse(List.of(RecordEntity.build("a.example.com", RecordType.A, 60, "1.1.1.1")),
|
||||||
new ResultInfo(1, 1, 2, 1, 2)))
|
new ResultInfo(1, 1, 2, 1, 2)))
|
||||||
@@ -490,7 +518,7 @@ class CfDnsClientMockTest {
|
|||||||
void testRecordListBySld_FetchesAllPages() throws Exception {
|
void testRecordListBySld_FetchesAllPages() throws Exception {
|
||||||
ZoneEntity zone = createTestZone();
|
ZoneEntity zone = createTestZone();
|
||||||
String base = "/zones/" + TEST_ZONE_ID + "/dns_records?name=test.example.com&order=name&direction=asc&page=%d&per_page="
|
String base = "/zones/" + TEST_ZONE_ID + "/dns_records?name=test.example.com&order=name&direction=asc&page=%d&per_page="
|
||||||
+ CfDnsClient.RECORDS_PER_PAGE;
|
+ CfDnsClient.MAX_RECORDS_PER_PAGE;
|
||||||
CfDnsClient spyClient = spy(client);
|
CfDnsClient spyClient = spy(client);
|
||||||
doReturn(recordResponse(List.of(RecordEntity.build("test.example.com", RecordType.A, 60, "1.1.1.1")),
|
doReturn(recordResponse(List.of(RecordEntity.build("test.example.com", RecordType.A, 60, "1.1.1.1")),
|
||||||
new ResultInfo(1, 1, 2, 1, 2)))
|
new ResultInfo(1, 1, 2, 1, 2)))
|
||||||
@@ -530,7 +558,7 @@ class CfDnsClientMockTest {
|
|||||||
|
|
||||||
verify(spyClient).getRequest(
|
verify(spyClient).getRequest(
|
||||||
eq("/zones/" + TEST_ZONE_ID + "/dns_records?name=example.com&order=name&direction=asc&page=1&per_page="
|
eq("/zones/" + TEST_ZONE_ID + "/dns_records?name=example.com&order=name&direction=asc&page=1&per_page="
|
||||||
+ CfDnsClient.RECORDS_PER_PAGE),
|
+ CfDnsClient.MAX_RECORDS_PER_PAGE),
|
||||||
eq(RecordMultipleResponse.class));
|
eq(RecordMultipleResponse.class));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -589,6 +617,22 @@ class CfDnsClientMockTest {
|
|||||||
.when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class));
|
.when(spyClient).getRequest(anyString(), eq(RecordMultipleResponse.class));
|
||||||
|
|
||||||
assertEquals(1, spyClient.recordList(createTestZone(), null).size());
|
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
|
@Test
|
||||||
@@ -601,10 +645,10 @@ class CfDnsClientMockTest {
|
|||||||
spyClient.recordListBySubdomain(createTestZone(), "www", RecordType.TXT);
|
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="
|
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + "/dns_records?type=MX&order=name&direction=asc&page=1&per_page="
|
||||||
+ CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
+ CfDnsClient.MAX_RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
||||||
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID
|
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID
|
||||||
+ "/dns_records?name=www.example.com&type=TXT&order=name&direction=asc&page=1&per_page="
|
+ "/dns_records?name=www.example.com&type=TXT&order=name&direction=asc&page=1&per_page="
|
||||||
+ CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
+ CfDnsClient.MAX_RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@@ -625,7 +669,7 @@ class CfDnsClientMockTest {
|
|||||||
|
|
||||||
assertEquals(List.of("A", "AAAA"), records.stream().map(RecordEntity::getType).toList());
|
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="
|
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID + "/dns_records?order=name&direction=asc&page=1&per_page="
|
||||||
+ CfDnsClient.RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
+ CfDnsClient.MAX_RECORDS_PER_PAGE), eq(RecordMultipleResponse.class));
|
||||||
}
|
}
|
||||||
|
|
||||||
private static RecordEntity fetchedMxRecord() {
|
private static RecordEntity fetchedMxRecord() {
|
||||||
@@ -759,10 +803,10 @@ class CfDnsClientMockTest {
|
|||||||
spyClient.recordListBySubdomain(createTestZone(), "0/26");
|
spyClient.recordListBySubdomain(createTestZone(), "0/26");
|
||||||
|
|
||||||
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID
|
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.RECORDS_PER_PAGE),
|
+ "/dns_records?name=%24%28reboot%29.example.com&order=name&direction=asc&page=1&per_page=" + CfDnsClient.MAX_RECORDS_PER_PAGE),
|
||||||
eq(RecordMultipleResponse.class));
|
eq(RecordMultipleResponse.class));
|
||||||
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID
|
verify(spyClient).getRequest(eq("/zones/" + TEST_ZONE_ID
|
||||||
+ "/dns_records?name=0%2F26.example.com&order=name&direction=asc&page=1&per_page=" + CfDnsClient.RECORDS_PER_PAGE),
|
+ "/dns_records?name=0%2F26.example.com&order=name&direction=asc&page=1&per_page=" + CfDnsClient.MAX_RECORDS_PER_PAGE),
|
||||||
eq(RecordMultipleResponse.class));
|
eq(RecordMultipleResponse.class));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -788,7 +832,7 @@ class CfDnsClientMockTest {
|
|||||||
|
|
||||||
private static String recordsPage(int page) {
|
private static String recordsPage(int page) {
|
||||||
return "/zones/" + TEST_ZONE_ID + "/dns_records?order=name&direction=asc&page=" + page
|
return "/zones/" + TEST_ZONE_ID + "/dns_records?order=name&direction=asc&page=" + page
|
||||||
+ "&per_page=" + CfDnsClient.RECORDS_PER_PAGE;
|
+ "&per_page=" + PagingRequest.MAX_PER_PAGE;
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
|
|||||||
@@ -9,7 +9,26 @@ public class PagingRequestTest {
|
|||||||
@Test
|
@Test
|
||||||
void testBuildPath() {
|
void testBuildPath() {
|
||||||
String result = PagingRequest.defaultPaging().addQueryString("/zones");
|
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
|
@Test
|
||||||
|
|||||||
Reference in new issue
Block a user