ai review (#1)
Build and Analyse / build-and-analyse (push) Successful in 1m20s

Co-authored-by: gitea-actions-bot <bot@mein-gateway.de>
Reviewed-on: #1
Co-authored-by: Thilo Schwarz <osp@thischwa.codes>
This commit is contained in:
thischwaandgitea-actions-bot authored and Thilo Schwarz committed 2026-11-06 14:28:06 +01:00
1 parent 4b560141a1
commit 8515f81621
32 files changed
+2223 -424

No files matched your search

@@ -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.
*
* <p>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 extends AbstractResponse> T executeRequest(ClassicHttpRequest request,
Class<T> 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<ResponseResultInfo.Error> 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<ResponseResultInfo.Error> errors) {
if (statusCode == HttpStatus.SC_NOT_FOUND) {
return new CloudflareNotFoundException(message, statusCode, errors);
}
return new CloudflareApiException(message, statusCode, errors);
}
/**
+365 -144
View File
@@ -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.
*
* <p>The client is thread-safe and should be reused. It holds a pool of HTTP connections, which is
* released by {@link #close()}.
*
* <p>Example with API token authentication (recommended):
* <pre><code>
* // 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&lt;RecordEntity&gt; records = cfDnsClient.recordList(zone, "sld");
* records.forEach(record ->
* System.out.println("Record Type: " + record.getType() + ", Value: " + record.getContent())
* );
* // Retrieve records of a subdomain
* List&lt;RecordEntity&gt; 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());
* }
* </code></pre>
*
* <p>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<ZoneEntity> 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<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());
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<ZoneEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> recordList(ZoneEntity zone, String sld, @Nullable RecordType... types)
public List<RecordEntity> 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<RecordEntity> recs = resp.getResult();
String fqdn = buildFqdn(zone, subdomain);
String endpoint = appendQuery(
addTypeFilter(CfRequest.RECORD_LIST_NAME.buildPath(zone.getId(), fqdn), types), RECORD_ORDER);
List<RecordEntity> 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<RecordEntity> recordList(ZoneEntity zone, RecordType... types)
public List<RecordEntity> 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<RecordEntity> recs = resp.getResult();
String endpoint = appendQuery(
addTypeFilter(CfRequest.RECORD_LIST.buildPath(zone.getId()), types), RECORD_ORDER);
List<RecordEntity> 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<RecordEntity> 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<RecordEntity> patchRecords, @Nullable List<RecordEntity> 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<RecordEntity> filterAndSetZoneRecords(ZoneEntity zone, @Nullable RecordType[] types, List<RecordEntity> recs)
private List<RecordEntity> filterAndSetZoneRecords(ZoneEntity zone, @Nullable RecordType[] types,
@Nullable List<RecordEntity> recs)
throws CloudflareNotFoundException {
if (recs == null) {
recs = List.of();
}
List<RecordEntity> filtered;
if (types != null && types.length > 0) {
Set<RecordType> allowedTypes = new HashSet<>(Arrays.asList(types));
Set<String> 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<RecordEntity> cleanRecordsForPostOrPut(List<RecordEntity> records) {
List<RecordEntity> cleaned = new ArrayList<>();
records.forEach(
rec -> cleaned.add(RecordEntity.build(rec.getId(), rec.getSld(), rec.getType(), rec.getTtl(), rec.getContent())));
return cleaned;
}
private List<RecordEntity> cleanRecordsForPatch(List<RecordEntity> records) {
List<RecordEntity> cleaned = new ArrayList<>();
records.forEach(rec -> cleaned.add(RecordEntity.build(rec.getId(), rec.getContent())));
return cleaned;
}
private List<RecordEntity> cleanRecordsForDelete(List<RecordEntity> records) {
List<RecordEntity> 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<RecordEntity> 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.
*
* <p>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 <E extends ResponseEntity, R extends AbstractMultipleResponse<E>> List<E> getAllPages(
String endpoint, Class<R> responseType, int perPage) throws CloudflareApiException {
List<E> result = List.of();
for (int attempt = 1; attempt <= MAX_PAGING_ATTEMPTS; attempt++) {
PagingResult<E> 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<E>(List<E> entries, int expectedCount) {
}
private <E extends ResponseEntity, R extends AbstractMultipleResponse<E>> PagingResult<E> fetchAllPagesOnce(
String endpoint, Class<R> responseType, int perPage) throws CloudflareApiException {
Map<String, E> byId = new LinkedHashMap<>();
List<E> 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<E> 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<E> all = new ArrayList<>(byId.values());
all.addAll(withoutId);
return new PagingResult<>(all, info == null || page == 1 ? -1 : expectedCount);
}
page++;
}
}
@@ -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<String> 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
* <p>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;
+51 -15
View File
@@ -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();
}
}
@@ -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.
*
* <p>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<ResponseResultInfo.Error> 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<ResponseResultInfo.Error> 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<ResponseResultInfo.Error> getErrors() {
return errors == null ? List.of() : errors;
}
}
@@ -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.
*
* <p>It extends {@link CloudflareApiException} to provide specific errors related to situations
* where Cloudflare responds with a "not found" operation.
* <p>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<ResponseResultInfo.Error> errors) {
super(message, statusCode, errors);
}
}
@@ -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.
* <li>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) {
@@ -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;
}
@@ -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<RecordEntity> 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<RecordEntity> 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);
}
}
@@ -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.
* <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 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
*/
@@ -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<RecordEntity> list(@Nullable RecordType... types) throws CloudflareApiException {
return client.recordList(zone, types);
return client.recordListByType(zone, types);
}
}
@@ -7,7 +7,9 @@ import lombok.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
* 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:
*
@@ -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<String, String> 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;
}
}
@@ -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;
* <li>Content of the DNS record, such as an IP address.
* <li>Flags indicating whether the record is proxiable or proxied.
* <li>TTL (Time-To-Live) for the DNS record.
* <li>Priority, required for MX and URI records (for SRV records it's part of the data).
* <li>Structured data, required for e.g. SRV, CAA, LOC or TLSA records instead of content.
* <li>An optional comment and tags.
* <li>A locked status to indicate the immutability of the record.
* <li>Zone-specific metadata including zone ID and name.
* <li>Timestamps for creation and modification.
* <li>Timestamps for creation and modification (UTC).
* </ul>
*
* <p>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<String> 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<String, Object> 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
* <p>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;
}
}
/**
* 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();
}
}
@@ -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;
* <li>Zone name.
* <li>Development mode status.
* <li>Active and original name servers linked to the zone.
* <li>Timestamps indicating when the zone was created, modified, or activated.
* <li>Timestamps (UTC) indicating when the zone was created, modified, or activated.
* <li>Current operational status of the zone (e.g., active, inactive).
* <li>Boolean flag indicating whether the zone is paused.
* <li>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<String> nameServers;
private Set<String> 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;
@@ -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, "<html><body>Bad Gateway</body></html>");
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;
}
}
}
@@ -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
@@ -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 + "'");
}
}
+274 -40
View File
@@ -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<RecordEntity> records = client.recordList(zone, SLD_STR, RecordType.A);
List<RecordEntity> 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<RecordEntity> aRecords = client.recordList(z, randomSld, RecordType.A);
List<RecordEntity> 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<RecordEntity> aaaaRecords = client.recordList(z, randomSld, RecordType.AAAA);
client.recordCreateSubdomain(z, randomSld, TTL, RecordType.AAAA, "2a0a:4cc0:c0:2e4::1");
List<RecordEntity> 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<RecordEntity> rList = client.recordList(z, randomSld);
List<RecordEntity> 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<RecordEntity> fullList = client.recordList(z);
// test recordList without SLD (the unfiltered list may lag behind directly after creating records)
List<RecordEntity> 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<RecordEntity> aList = client.recordList(z, RecordType.A);
List<RecordEntity> 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<RecordEntity> records1 = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> patchRecords = new ArrayList<>();
for (int i = 0; i < 2; i++) {
List<RecordEntity> records = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> deleteRecords = new ArrayList<>();
for (int i = 0; i < 2; i++) {
List<RecordEntity> records = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> putRecords = new ArrayList<>();
for (int i = 0; i < 2; i++) {
List<RecordEntity> records = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> updatedRecords = client.recordList(zone, sldNames.get(i), RecordType.A);
List<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<String> 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<String> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> awaitRecords(RecordQuery query,
java.util.function.Predicate<List<RecordEntity>> condition)
throws CloudflareApiException, InterruptedException {
List<RecordEntity> 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;
}
}
@@ -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());
}
}
@@ -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<RecordEntity> records = spyClient.recordList(zone, "test");
List<RecordEntity> 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<RecordEntity> records = spyClient.recordList(zone, "test", RecordType.A);
List<RecordEntity> 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<RecordEntity> records = spyClient.recordList(zone, RecordType.A);
List<RecordEntity> 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<ZoneEntity> zones, ResultInfo resultInfo) {
ZoneMultipleResponse resp = new ZoneMultipleResponse();
resp.setResult(zones);
resp.setResultInfo(resultInfo);
resp.setResponseResultInfo(createSuccessResultInfo());
return resp;
}
private RecordMultipleResponse recordResponse(List<RecordEntity> 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<ZoneEntity> 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<RecordEntity> 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<RecordEntity> 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<Object> 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<RecordEntity> 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<Object> 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<Object> 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<Object> 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`",
"<script>alert('x')</script>", "\"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<RecordEntity> 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<RecordEntity> 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));
}
}
@@ -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"));
}
}
@@ -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);
}
}
@@ -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));
}
}
private static ZoneMultipleResponse zoneResponse(int count) {
ZoneMultipleResponse resp = new ZoneMultipleResponse();
ResponseResultInfo info = new ResponseResultInfo();
info.setSuccess(true);
resp.setResponseResultInfo(info);
List<ZoneEntity> 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));
}
}
@@ -59,7 +59,7 @@ class FluentApiTest {
RecordEntity rec2 = RecordEntity.build("www.example.com", RecordType.A, 300, "1.2.3.5");
List<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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<RecordEntity> 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);
@@ -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
@@ -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());
}
}
@@ -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<String> 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);