Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(ecr): manage pull through cache rules (#4304)

XuJian1952ba4052d5
diff --git a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcrTest.java b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcrTest.java
index caef53b676..b4db72f0fa 100644
--- a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcrTest.java
+++ b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcrTest.java
@@ -151,4 +151,54 @@ class EcrTest {
b -> b.repositoryNames("does-not-exist-" + System.nanoTime())))
.isInstanceOf(RepositoryNotFoundException.class);
}
+
+ @Test
+ @Order(11)
+ @DisplayName("Pull through cache rules round-trip through the AWS SDK")
+ void pullThroughCacheRuleLifecycle() {
+ String firstPrefix = "sdk-docker-hub";
+ String secondPrefix = "sdk-kubernetes";
+ try {
+ CreatePullThroughCacheRuleResponse created = ecr.createPullThroughCacheRule(builder -> builder
+ .ecrRepositoryPrefix(firstPrefix)
+ .upstreamRegistryUrl("registry-1.docker.io"));
+ ecr.createPullThroughCacheRule(builder -> builder
+ .ecrRepositoryPrefix(secondPrefix)
+ .upstreamRegistryUrl("registry.k8s.io"));
+
+ assertThat(created.ecrRepositoryPrefix()).isEqualTo(firstPrefix);
+ assertThat(created.upstreamRegistry()).isEqualTo(UpstreamRegistry.DOCKER_HUB);
+ assertThat(created.upstreamRepositoryPrefix()).isEqualTo("ROOT");
+ assertThat(created.createdAt()).isNotNull();
+
+ DescribePullThroughCacheRulesResponse firstPage = ecr.describePullThroughCacheRules(
+ builder -> builder.maxResults(1));
+ DescribePullThroughCacheRulesResponse secondPage = ecr.describePullThroughCacheRules(
+ builder -> builder.maxResults(1).nextToken(firstPage.nextToken()));
+ DescribePullThroughCacheRulesResponse filtered = ecr.describePullThroughCacheRules(
+ builder -> builder.ecrRepositoryPrefixes(firstPrefix));
+
+ assertThat(firstPage.pullThroughCacheRules()).hasSize(1);
+ assertThat(firstPage.nextToken()).isNotBlank();
+ assertThat(secondPage.pullThroughCacheRules()).hasSize(1);
+ assertThat(filtered.pullThroughCacheRules())
+ .extracting(PullThroughCacheRule::ecrRepositoryPrefix)
+ .containsExactly(firstPrefix);
+
+ DeletePullThroughCacheRuleResponse deleted = ecr.deletePullThroughCacheRule(
+ builder -> builder.ecrRepositoryPrefix(firstPrefix));
+ assertThat(deleted.ecrRepositoryPrefix()).isEqualTo(firstPrefix);
+ assertThatThrownBy(() -> ecr.deletePullThroughCacheRule(
+ builder -> builder.ecrRepositoryPrefix(firstPrefix)))
+ .isInstanceOf(PullThroughCacheRuleNotFoundException.class);
+ } finally {
+ for (String prefix : List.of(firstPrefix, secondPrefix)) {
+ try {
+ ecr.deletePullThroughCacheRule(builder -> builder.ecrRepositoryPrefix(prefix));
+ } catch (PullThroughCacheRuleNotFoundException expected) {
+ // The rule was already deleted by the lifecycle assertion.
+ }
+ }
+ }
+ }
}
diff --git a/docs/services/ecr.md b/docs/services/ecr.md
index c48be034fa..040a9dceac 100644
--- a/docs/services/ecr.md
+++ b/docs/services/ecr.md
@@ -9,6 +9,9 @@
| Action | Description |
| --- | --- |
| `CreateRepository` | Create a new repository (lazy-starts the backing registry on first call) |
+| `CreatePullThroughCacheRule` | Create and persist pull-through cache rule configuration |
+| `DescribePullThroughCacheRules` | List or filter pull-through cache rules with pagination |
+| `DeletePullThroughCacheRule` | Delete a pull-through cache rule by repository prefix |
| `DescribeRepositories` | List repositories or fetch by name |
| `DeleteRepository` | Delete a repository (with `force=true` semantics for non-empty repos) |
| `GetAuthorizationToken` | Returns a docker-login token + proxy endpoint |
@@ -36,6 +39,7 @@
- **Loopback URI scheme.** Repository URIs follow `<account>.dkr.ecr.<region>.localhost:<flociPort>/<repoName>`. RFC 6761 reserves `*.localhost` to resolve to the loopback address, and the docker daemon auto-trusts loopback as an insecure registry, so `docker push` and `docker pull` work without daemon configuration. A `path` URI style fallback (`localhost:<flociPort>/<account>/<region>/<repo>`) is available via `floci.services.ecr.uri-style: path` for environments where `*.localhost` resolution misbehaves.
- **Image tag mutability.** `IMMUTABLE` repositories allow the first manifest write for a tag and reject every replacement, including a replacement with the same manifest. The proxy forwards blob uploads and digest-addressed manifests unchanged.
- **Authorization.** `GetAuthorizationToken` returns `Base64("AWS:floci")` plus a proxy endpoint. The backing `registry:2` runs without auth, so any `aws ecr get-login-password | docker login` succeeds.
+- **Pull through cache rule configuration.** `CreatePullThroughCacheRule`, `DescribePullThroughCacheRules`, and `DeletePullThroughCacheRule` persist AWS-compatible rule metadata with account and Region isolation. Rules do not proxy or cache images from the configured upstream registry.
- **Manifest format negotiation.** `BatchGetImage` forwards the caller's `acceptedMediaTypes` as the upstream `Accept` header. Modern OCI manifests (`application/vnd.oci.image.manifest.v1+json`) and Docker v2 schema 2 are both supported.
- **Cross-account / cross-region isolation.** Internally the registry namespaces repositories as `<account>/<region>/<repoName>`, so the same repository name in different accounts or regions cannot collide.
- **Reconcile on first start.** When the registry container starts, Floci queries `GET /v2/_catalog` and recreates `Repository` metadata entries for any namespaces present in the registry but missing from local storage. This means image bytes are never orphaned across restarts.
@@ -227,7 +231,8 @@ new lambda.DockerImageFunction(this, 'MyFn', {
The following ECR features are **not** implemented. Stored values for policies and lifecycle rules round-trip via the API but are not enforced at runtime:
-- Replication and pull-through cache
+- Replication
+- Pull-through cache image proxying and population. Rule configuration APIs are supported, but pulls are not routed to upstream registries
- Image scanning (`StartImageScan`, `DescribeImageScanFindings`)
- Image signing and notary attachments
- Lifecycle policy enforcement (the policy text is stored but not applied)
diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/EcrJsonHandler.java b/src/main/java/io/github/hectorvent/floci/services/ecr/EcrJsonHandler.java
index 16f89f903c..0afa86f5d6 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ecr/EcrJsonHandler.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/EcrJsonHandler.java
@@ -6,11 +6,14 @@ import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import io.github.hectorvent.floci.core.common.AwsArnUtils;
import io.github.hectorvent.floci.core.common.AwsErrorResponse;
+import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
import io.github.hectorvent.floci.services.ecr.model.AuthorizationData;
import io.github.hectorvent.floci.services.ecr.model.Image;
import io.github.hectorvent.floci.services.ecr.model.ImageDetail;
import io.github.hectorvent.floci.services.ecr.model.ImageFailure;
import io.github.hectorvent.floci.services.ecr.model.ImageIdentifier;
+import io.github.hectorvent.floci.services.ecr.model.PullThroughCacheRule;
import io.github.hectorvent.floci.services.ecr.model.Repository;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
@@ -41,6 +44,9 @@ public class EcrJsonHandler {
public Response handle(String action, JsonNode request, String region) {
return switch (action) {
case "CreateRepository" -> handleCreateRepository(request, region);
+ case "CreatePullThroughCacheRule" -> handleCreatePullThroughCacheRule(request, region);
+ case "DescribePullThroughCacheRules" -> handleDescribePullThroughCacheRules(request, region);
+ case "DeletePullThroughCacheRule" -> handleDeletePullThroughCacheRule(request, region);
case "DescribeRepositories" -> handleDescribeRepositories(request, region);
case "BatchGetRepositoryScanningConfiguration" ->
handleBatchGetRepositoryScanningConfiguration(request, region);
@@ -86,6 +92,50 @@ public class EcrJsonHandler {
return Response.ok(response).build();
}
+ private Response handleCreatePullThroughCacheRule(JsonNode request, String region) {
+ PullThroughCacheRule rule = service.createPullThroughCacheRule(
+ request.path("ecrRepositoryPrefix").asText(null),
+ request.path("upstreamRegistryUrl").asText(null),
+ request.path("registryId").asText(null),
+ request.path("upstreamRegistry").asText(null),
+ request.path("credentialArn").asText(null),
+ request.path("customRoleArn").asText(null),
+ request.path("upstreamRepositoryPrefix").asText(null),
+ region);
+ return Response.ok(buildPullThroughCacheRule(rule, true, false)).build();
+ }
+
+ private Response handleDescribePullThroughCacheRules(JsonNode request, String region) {
+ JsonNode prefixesNode = request.path("ecrRepositoryPrefixes");
+ List<String> prefixes = prefixesNode.isMissingNode() || prefixesNode.isNull()
+ ? null
+ : parseStringList(prefixesNode);
+ PaginatedResult<PullThroughCacheRule> result = service.describePullThroughCacheRules(
+ request.path("registryId").asText(null),
+ prefixes,
+ parseMaxResults(request.path("maxResults")),
+ request.path("nextToken").asText(null),
+ region);
+ ObjectNode response = objectMapper.createObjectNode();
+ ArrayNode rules = objectMapper.createArrayNode();
+ for (PullThroughCacheRule rule : result.items()) {
+ rules.add(buildPullThroughCacheRule(rule, true, true));
+ }
+ response.set("pullThroughCacheRules", rules);
+ if (result.nextToken() != null) {
+ response.put("nextToken", result.nextToken());
+ }
+ return Response.ok(response).build();
+ }
+
+ private Response handleDeletePullThroughCacheRule(JsonNode request, String region) {
+ PullThroughCacheRule rule = service.deletePullThroughCacheRule(
+ request.path("ecrRepositoryPrefix").asText(null),
+ request.path("registryId").asText(null),
+ region);
+ return Response.ok(buildPullThroughCacheRule(rule, false, false)).build();
+ }
+
private Response handleDescribeRepositories(JsonNode request, String region) {
List<String> names = parseStringList(request.path("repositoryNames"));
String registryId = request.path("registryId").asText(null);
@@ -381,6 +431,32 @@ public class EcrJsonHandler {
return n;
}
+ private ObjectNode buildPullThroughCacheRule(PullThroughCacheRule rule,
+ boolean includeUpstreamRegistry,
+ boolean includeUpdatedAt) {
+ ObjectNode response = objectMapper.createObjectNode();
+ response.put("ecrRepositoryPrefix", rule.getEcrRepositoryPrefix());
+ response.put("upstreamRegistryUrl", rule.getUpstreamRegistryUrl());
+ response.put("createdAt", rule.getCreatedAt().getEpochSecond());
+ response.put("registryId", rule.getRegistryId());
+ if (rule.getCredentialArn() != null) {
+ response.put("credentialArn", rule.getCredentialArn());
+ }
+ if (rule.getCustomRoleArn() != null) {
+ response.put("customRoleArn", rule.getCustomRoleArn());
+ }
+ if (rule.getUpstreamRepositoryPrefix() != null) {
+ response.put("upstreamRepositoryPrefix", rule.getUpstreamRepositoryPrefix());
+ }
+ if (includeUpstreamRegistry && rule.getUpstreamRegistry() != null) {
+ response.put("upstreamRegistry", rule.getUpstreamRegistry());
+ }
+ if (includeUpdatedAt && rule.getUpdatedAt() != null) {
+ response.put("updatedAt", rule.getUpdatedAt().getEpochSecond());
+ }
+ return response;
+ }
+
private ObjectNode buildImageDetail(ImageDetail d) {
ObjectNode n = objectMapper.createObjectNode();
n.put("registryId", d.getRegistryId());
@@ -464,6 +540,16 @@ public class EcrJsonHandler {
return out;
}
+ private static Integer parseMaxResults(JsonNode node) {
+ if (node == null || node.isMissingNode() || node.isNull()) {
+ return null;
+ }
+ if (!node.isIntegralNumber() || !node.canConvertToInt()) {
+ throw new AwsException("InvalidParameterException", "maxResults must be an integer.", 400);
+ }
+ return node.intValue();
+ }
+
private static Map<String, String> parseTags(JsonNode node) {
if (node == null || node.isMissingNode() || node.isNull() || !node.isArray()) {
return new HashMap<>();
diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/EcrService.java b/src/main/java/io/github/hectorvent/floci/services/ecr/EcrService.java
index bdfbf20f4d..778e41d464 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ecr/EcrService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/EcrService.java
@@ -1,9 +1,11 @@
package io.github.hectorvent.floci.services.ecr;
import io.github.hectorvent.floci.config.EmulatorConfig;
-import io.github.hectorvent.floci.core.common.RegionResolver;
import io.github.hectorvent.floci.core.common.AwsArnUtils;
import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
+import io.github.hectorvent.floci.core.common.Pagination;
+import io.github.hectorvent.floci.core.common.RegionResolver;
import io.github.hectorvent.floci.core.resource.ExplorerResource;
import io.github.hectorvent.floci.core.resource.ResourceProvider;
import io.github.hectorvent.floci.core.resource.SupportedResourceType;
@@ -16,6 +18,7 @@ import io.github.hectorvent.floci.services.ecr.model.ImageFailure;
import io.github.hectorvent.floci.services.ecr.model.ImageIdentifier;
import io.github.hectorvent.floci.services.ecr.model.ImageMetadata;
import io.github.hectorvent.floci.services.ecr.model.Image;
+import io.github.hectorvent.floci.services.ecr.model.PullThroughCacheRule;
import io.github.hectorvent.floci.services.ecr.model.Repository;
import io.github.hectorvent.floci.services.ecr.registry.EcrRegistryManager;
import io.github.hectorvent.floci.services.ecr.registry.RegistryHttpClient;
@@ -39,10 +42,23 @@ public class EcrService implements ResourceProvider {
private static final Logger LOG = Logger.getLogger(EcrService.class);
private static final Pattern REPO_NAME = Pattern.compile(
"(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*");
+ private static final Pattern PULL_THROUGH_CACHE_PREFIX = Pattern.compile(
+ "(?:[a-z0-9]+(?:(?:\\.|_|__|-+)[a-z0-9]+)*(?:/[a-z0-9]+"
+ + "(?:(?:\\.|_|__|-+)[a-z0-9]+)*)*/?|ROOT)");
+ private static final Pattern REGISTRY_ID = Pattern.compile("[0-9]{12}");
+ private static final Pattern CREDENTIAL_ARN = Pattern.compile(
+ "arn:aws(?:-\\w+)*:secretsmanager:[a-zA-Z0-9-:]+:secret:ecr-pullthroughcache/"
+ + "[a-zA-Z0-9/_+=.@-]+");
+ private static final Set<String> UPSTREAM_REGISTRIES = Set.of(
+ "ecr", "ecr-public", "quay", "k8s", "docker-hub",
+ "github-container-registry", "azure-container-registry",
+ "gitlab-container-registry", "chainguard");
private static final int MAX_REPO_NAME_LENGTH = 256;
+ private static final int MAX_PULL_THROUGH_CACHE_PREFIX_LENGTH = 30;
private final StorageBackend<String, Repository> repoStore;
private final StorageBackend<String, ImageMetadata> imageMetaStore;
+ private final StorageBackend<String, PullThroughCacheRule> pullThroughCacheRuleStore;
private final EcrRegistryManager registryManager;
private final EmulatorConfig config;
private final RegionResolver regionResolver;
@@ -56,22 +72,119 @@ public class EcrService implements ResourceProvider {
new TypeReference<Map<String, Repository>>() {}),
factory.create("ecr", "image-metadata.json",
new TypeReference<Map<String, ImageMetadata>>() {}),
+ factory.create("ecr", "pull-through-cache-rules.json",
+ new TypeReference<Map<String, PullThroughCacheRule>>() {}),
registryManager, config, regionResolver);
}
EcrService(StorageBackend<String, Repository> repoStore,
StorageBackend<String, ImageMetadata> imageMetaStore,
+ StorageBackend<String, PullThroughCacheRule> pullThroughCacheRuleStore,
EcrRegistryManager registryManager,
EmulatorConfig config,
RegionResolver regionResolver) {
this.repoStore = repoStore;
this.imageMetaStore = imageMetaStore;
+ this.pullThroughCacheRuleStore = pullThroughCacheRuleStore;
this.registryManager = registryManager;
this.config = config;
this.regionResolver = regionResolver;
this.registryManager.setReconcileHook(this::reconcileFromCatalog);
}
+ // ============================================================
+ // Pull through cache rules
+ // ============================================================
+
+ public PullThroughCacheRule createPullThroughCacheRule(String ecrRepositoryPrefix,
+ String upstreamRegistryUrl,
+ String registryId,
+ String upstreamRegistry,
+ String credentialArn,
+ String customRoleArn,
+ String upstreamRepositoryPrefix,
+ String region) {
+ String prefix = normalizePullThroughCachePrefix(ecrRepositoryPrefix);
+ validatePullThroughCachePrefix(prefix, "ecrRepositoryPrefix");
+ validateUpstreamRegistryUrl(upstreamRegistryUrl);
+ validateCredentialArn(credentialArn);
+ validateCustomRoleArn(customRoleArn);
+ String upstreamPrefix = upstreamRepositoryPrefix == null || upstreamRepositoryPrefix.isBlank()
+ ? "ROOT"
+ : normalizePullThroughCachePrefix(upstreamRepositoryPrefix);
+ validatePullThroughCachePrefix(upstreamPrefix, "upstreamRepositoryPrefix");
+ if ("ROOT".equals(prefix) && !"ROOT".equals(upstreamPrefix)) {
+ throw new AwsException("InvalidParameterException",
+ "upstreamRepositoryPrefix must be ROOT when ecrRepositoryPrefix is ROOT", 400);
+ }
+ String account = effectiveAccount(registryId);
+ validateRegistryId(account);
+ String resolvedUpstreamRegistry = resolveUpstreamRegistry(upstreamRegistry, upstreamRegistryUrl);
+ String key = pullThroughCacheRuleKey(region, account, prefix);
+ if (pullThroughCacheRuleStore.get(key).isPresent()) {
+ throw new AwsException("PullThroughCacheRuleAlreadyExistsException",
+ "A pull through cache rule with repository prefix '" + prefix
+ + "' already exists in registry '" + account + "'", 400);
+ }
+
+ Instant now = Instant.now();
+ PullThroughCacheRule rule = new PullThroughCacheRule();
+ rule.setRegistryId(account);
+ rule.setEcrRepositoryPrefix(prefix);
+ rule.setUpstreamRegistryUrl(upstreamRegistryUrl);
+ rule.setUpstreamRegistry(resolvedUpstreamRegistry);
+ rule.setCredentialArn(credentialArn);
+ rule.setCustomRoleArn(customRoleArn);
+ rule.setUpstreamRepositoryPrefix(upstreamPrefix);
+ rule.setCreatedAt(now);
+ rule.setUpdatedAt(now);
+ pullThroughCacheRuleStore.put(key, rule);
+ return rule;
+ }
+
+ public PaginatedResult<PullThroughCacheRule> describePullThroughCacheRules(
+ String registryId,
+ List<String> ecrRepositoryPrefixes,
+ Integer maxResults,
+ String nextToken,
+ String region) {
+ String account = effectiveAccount(registryId);
+ validateRegistryId(account);
+ List<PullThroughCacheRule> rules;
+ if (ecrRepositoryPrefixes == null) {
+ String keyPrefix = region + "::" + account + "::";
+ rules = pullThroughCacheRuleStore.scan(key -> key.startsWith(keyPrefix));
+ } else {
+ if (ecrRepositoryPrefixes.isEmpty() || ecrRepositoryPrefixes.size() > 100) {
+ throw new AwsException("InvalidParameterException",
+ "ecrRepositoryPrefixes must contain between 1 and 100 items", 400);
+ }
+ rules = new ArrayList<>();
+ for (String requestedPrefix : ecrRepositoryPrefixes) {
+ String prefix = normalizePullThroughCachePrefix(requestedPrefix);
+ validatePullThroughCachePrefix(prefix, "ecrRepositoryPrefixes");
+ rules.add(pullThroughCacheRuleStore.get(pullThroughCacheRuleKey(region, account, prefix))
+ .orElseThrow(() -> pullThroughCacheRuleNotFound(prefix, account)));
+ }
+ }
+ return Pagination.paginate(rules, PullThroughCacheRule::getEcrRepositoryPrefix,
+ maxResults, nextToken, 100, 1000, "InvalidParameterException");
+ }
+
+ public PullThroughCacheRule deletePullThroughCacheRule(String ecrRepositoryPrefix,
+ String registryId,
+ String region) {
+ String prefix = normalizePullThroughCachePrefix(ecrRepositoryPrefix);
+ validatePullThroughCachePrefix(prefix, "ecrRepositoryPrefix");
+ String account = effectiveAccount(registryId);
+ validateRegistryId(account);
+ String key = pullThroughCacheRuleKey(region, account, prefix);
+ PullThroughCacheRule rule = pullThroughCacheRuleStore.get(key)
+ .orElseThrow(() -> pullThroughCacheRuleNotFound(prefix, account));
+ pullThroughCacheRuleStore.delete(key);
+ return rule;
+ }
+
/**
* Recreates {@link Repository} metadata entries for registry namespaces found in the catalog.
* Namespaces created by Floci are {@code <account>/<region>/<repoName>}; pre-proxy registry
@@ -608,6 +721,10 @@ public class EcrService implements ResourceProvider {
return key(region, account, repoName) + "::" + digest;
}
+ private static String pullThroughCacheRuleKey(String region, String account, String prefix) {
+ return region + "::" + account + "::" + prefix;
+ }
+
/**
* Gate for the ECR data plane, which cannot be emulated without the backing
@@ -771,6 +888,110 @@ public class EcrService implements ResourceProvider {
return regionResolver.getAccountId();
}
+ private static String normalizePullThroughCachePrefix(String prefix) {
+ if (prefix == null || prefix.isBlank() || "ROOT".equals(prefix)) {
+ return prefix;
+ }
+ return prefix.endsWith("/") ? prefix.substring(0, prefix.length() - 1) : prefix;
+ }
+
+ private static void validatePullThroughCachePrefix(String prefix, String fieldName) {
+ if (prefix == null || prefix.length() < 2 || prefix.length() > MAX_PULL_THROUGH_CACHE_PREFIX_LENGTH
+ || !PULL_THROUGH_CACHE_PREFIX.matcher(prefix).matches()) {
+ throw new AwsException("InvalidParameterException",
+ fieldName + " must match the ECR pull through cache repository prefix pattern", 400);
+ }
+ }
+
+ private static void validateRegistryId(String registryId) {
+ if (!REGISTRY_ID.matcher(registryId).matches()) {
+ throw new AwsException("InvalidParameterException",
+ "registryId must be a 12 digit account ID", 400);
+ }
+ }
+
+ private static void validateUpstreamRegistryUrl(String upstreamRegistryUrl) {
+ if (upstreamRegistryUrl == null || upstreamRegistryUrl.isBlank()) {
+ throw new AwsException("InvalidParameterException",
+ "upstreamRegistryUrl must not be empty", 400);
+ }
+ }
+
+ private static void validateCredentialArn(String credentialArn) {
+ if (credentialArn == null) {
+ return;
+ }
+ if (credentialArn.length() < 50 || credentialArn.length() > 612
+ || !CREDENTIAL_ARN.matcher(credentialArn).matches()) {
+ throw new AwsException("InvalidParameterException",
+ "credentialArn does not match the ECR pull through cache secret ARN pattern", 400);
+ }
+ }
+
+ private static void validateCustomRoleArn(String customRoleArn) {
+ if (customRoleArn != null && customRoleArn.length() > 2048) {
+ throw new AwsException("InvalidParameterException",
+ "customRoleArn exceeds 2048 characters", 400);
+ }
+ }
+
+ private static String resolveUpstreamRegistry(String upstreamRegistry, String upstreamRegistryUrl) {
+ if (upstreamRegistry != null && !upstreamRegistry.isBlank()) {
+ if (!UPSTREAM_REGISTRIES.contains(upstreamRegistry)) {
+ throw unsupportedUpstreamRegistry(upstreamRegistry);
+ }
+ return upstreamRegistry;
+ }
+ String host = upstreamRegistryUrl.toLowerCase();
+ if (host.startsWith("https://")) {
+ host = host.substring("https://".length());
+ } else if (host.startsWith("http://")) {
+ host = host.substring("http://".length());
+ }
+ while (host.endsWith("/")) {
+ host = host.substring(0, host.length() - 1);
+ }
+ if (host.equals("registry-1.docker.io")) {
+ return "docker-hub";
+ }
+ if (host.equals("public.ecr.aws")) {
+ return "ecr-public";
+ }
+ if (host.equals("quay.io")) {
+ return "quay";
+ }
+ if (host.equals("registry.k8s.io")) {
+ return "k8s";
+ }
+ if (host.equals("ghcr.io")) {
+ return "github-container-registry";
+ }
+ if (host.equals("registry.gitlab.com")) {
+ return "gitlab-container-registry";
+ }
+ if (host.endsWith(".azurecr.io")) {
+ return "azure-container-registry";
+ }
+ if (host.equals("cgr.dev")) {
+ return "chainguard";
+ }
+ if (host.matches("[0-9]{12}\\.dkr\\.ecr\\.[a-z0-9-]+\\.amazonaws\\.com(?:\\.cn)?")) {
+ return "ecr";
+ }
+ throw unsupportedUpstreamRegistry(upstreamRegistryUrl);
+ }
+
+ private static AwsException unsupportedUpstreamRegistry(String value) {
+ return new AwsException("UnsupportedUpstreamRegistryException",
+ "The upstream registry '" + value + "' is not supported", 400);
+ }
+
+ private static AwsException pullThroughCacheRuleNotFound(String prefix, String account) {
+ return new AwsException("PullThroughCacheRuleNotFoundException",
+ "The pull through cache rule with repository prefix '" + prefix
+ + "' does not exist in registry '" + account + "'", 400);
+ }
+
private static void validateRepoName(String name) {
if (name == null || name.isBlank()) {
throw new AwsException("InvalidParameterException",
diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/model/PullThroughCacheRule.java b/src/main/java/io/github/hectorvent/floci/services/ecr/model/PullThroughCacheRule.java
new file mode 100644
index 0000000000..f0aeac7104
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/model/PullThroughCacheRule.java
@@ -0,0 +1,54 @@
+package io.github.hectorvent.floci.services.ecr.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+import java.time.Instant;
+
+/** Mutable ECR pull through cache rule for Jackson persistence. */
+@RegisterForReflection
+public class PullThroughCacheRule {
+ private String registryId;
+ private String ecrRepositoryPrefix;
+ private String upstreamRegistryUrl;
+ private String upstreamRegistry;
+ private String credentialArn;
+ private String customRoleArn;
+ private String upstreamRepositoryPrefix;
+ private Instant createdAt;
+ private Instant updatedAt;
+
+ public PullThroughCacheRule() {}
+
+ public String getRegistryId() { return registryId; }
+ public void setRegistryId(String registryId) { this.registryId = registryId; }
+
+ public String getEcrRepositoryPrefix() { return ecrRepositoryPrefix; }
+ public void setEcrRepositoryPrefix(String ecrRepositoryPrefix) {
+ this.ecrRepositoryPrefix = ecrRepositoryPrefix;
+ }
+
+ public String getUpstreamRegistryUrl() { return upstreamRegistryUrl; }
+ public void setUpstreamRegistryUrl(String upstreamRegistryUrl) {
+ this.upstreamRegistryUrl = upstreamRegistryUrl;
+ }
+
+ public String getUpstreamRegistry() { return upstreamRegistry; }
+ public void setUpstreamRegistry(String upstreamRegistry) { this.upstreamRegistry = upstreamRegistry; }
+
+ public String getCredentialArn() { return credentialArn; }
+ public void setCredentialArn(String credentialArn) { this.credentialArn = credentialArn; }
+
+ public String getCustomRoleArn() { return customRoleArn; }
+ public void setCustomRoleArn(String customRoleArn) { this.customRoleArn = customRoleArn; }
+
+ public String getUpstreamRepositoryPrefix() { return upstreamRepositoryPrefix; }
+ public void setUpstreamRepositoryPrefix(String upstreamRepositoryPrefix) {
+ this.upstreamRepositoryPrefix = upstreamRepositoryPrefix;
+ }
+
+ public Instant getCreatedAt() { return createdAt; }
+ public void setCreatedAt(Instant createdAt) { this.createdAt = createdAt; }
+
+ public Instant getUpdatedAt() { return updatedAt; }
+ public void setUpdatedAt(Instant updatedAt) { this.updatedAt = updatedAt; }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/ecr/EcrIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/ecr/EcrIntegrationTest.java
index 86c1bafd14..401e19ceae 100644
--- a/src/test/java/io/github/hectorvent/floci/services/ecr/EcrIntegrationTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/ecr/EcrIntegrationTest.java
@@ -29,6 +29,8 @@ class EcrIntegrationTest {
private static final String CT = "application/x-amz-json-1.1";
private static final String PREFIX = "AmazonEC2ContainerRegistry_V20150921.";
private static final String REPO = "floci-it/integration";
+ private static final String CACHE_PREFIX = "docker-hub";
+ private static final String SECOND_CACHE_PREFIX = "kubernetes";
private static final String WEST_REGION = "us-west-2";
private static final String WEST_CREDENTIAL =
"AWS4-HMAC-SHA256 Credential=000000000000/20260923/" + WEST_REGION + "/ecr/aws4_request";
@@ -260,4 +262,149 @@ class EcrIntegrationTest {
.then()
.statusCode(200);
}
+
+ @Test
+ @Order(11)
+ void createPullThroughCacheRule() {
+ given()
+ .header("X-Amz-Target", PREFIX + "CreatePullThroughCacheRule")
+ .contentType(CT)
+ .body("""
+ {
+ "ecrRepositoryPrefix": "%s/",
+ "upstreamRegistryUrl": "registry-1.docker.io",
+ "credentialArn": "arn:aws:secretsmanager:us-east-1:000000000000:secret:ecr-pullthroughcache/docker-hub",
+ "upstreamRepositoryPrefix": "library"
+ }
+ """.formatted(CACHE_PREFIX))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("ecrRepositoryPrefix", equalTo(CACHE_PREFIX))
+ .body("upstreamRegistryUrl", equalTo("registry-1.docker.io"))
+ .body("upstreamRegistry", equalTo("docker-hub"))
+ .body("upstreamRepositoryPrefix", equalTo("library"))
+ .body("registryId", equalTo("000000000000"))
+ .body("createdAt", notNullValue());
+
+ given()
+ .header("X-Amz-Target", PREFIX + "CreatePullThroughCacheRule")
+ .contentType(CT)
+ .body("""
+ {
+ "ecrRepositoryPrefix": "%s",
+ "upstreamRegistryUrl": "registry.k8s.io"
+ }
+ """.formatted(SECOND_CACHE_PREFIX))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("upstreamRegistry", equalTo("k8s"))
+ .body("upstreamRepositoryPrefix", equalTo("ROOT"));
+ }
+
+ @Test
+ @Order(12)
+ void describePullThroughCacheRulesFiltersAndPaginates() {
+ String nextToken = given()
+ .header("X-Amz-Target", PREFIX + "DescribePullThroughCacheRules")
+ .contentType(CT)
+ .body("{ \"maxResults\": 1 }")
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("pullThroughCacheRules", hasSize(1))
+ .body("pullThroughCacheRules[0].createdAt", notNullValue())
+ .body("pullThroughCacheRules[0].updatedAt", notNullValue())
+ .body("nextToken", not(emptyString()))
+ .extract().jsonPath().getString("nextToken");
+
+ given()
+ .header("X-Amz-Target", PREFIX + "DescribePullThroughCacheRules")
+ .contentType(CT)
+ .body("""
+ { "maxResults": 1, "nextToken": "%s" }
+ """.formatted(nextToken))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("pullThroughCacheRules", hasSize(1));
+
+ given()
+ .header("X-Amz-Target", PREFIX + "DescribePullThroughCacheRules")
+ .contentType(CT)
+ .body("""
+ { "ecrRepositoryPrefixes": ["%s/"] }
+ """.formatted(CACHE_PREFIX))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("pullThroughCacheRules", hasSize(1))
+ .body("pullThroughCacheRules[0].ecrRepositoryPrefix", equalTo(CACHE_PREFIX));
+ }
+
+ @Test
+ @Order(13)
+ void createPullThroughCacheRuleDuplicateFails() {
+ given()
+ .header("X-Amz-Target", PREFIX + "CreatePullThroughCacheRule")
+ .contentType(CT)
+ .body("""
+ {
+ "ecrRepositoryPrefix": "%s",
+ "upstreamRegistryUrl": "registry-1.docker.io"
+ }
+ """.formatted(CACHE_PREFIX))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(400)
+ .body("__type", equalTo("PullThroughCacheRuleAlreadyExistsException"));
+
+ given()
+ .header("X-Amz-Target", PREFIX + "DescribePullThroughCacheRules")
+ .contentType(CT)
+ .body("{ \"ecrRepositoryPrefixes\": [] }")
+ .when()
+ .post("/")
+ .then()
+ .statusCode(400)
+ .body("__type", equalTo("InvalidParameterException"));
+ }
+
+ @Test
+ @Order(14)
+ void deletePullThroughCacheRules() {
+ for (String prefix : new String[] {CACHE_PREFIX, SECOND_CACHE_PREFIX}) {
+ given()
+ .header("X-Amz-Target", PREFIX + "DeletePullThroughCacheRule")
+ .contentType(CT)
+ .body("""
+ { "ecrRepositoryPrefix": "%s" }
+ """.formatted(prefix))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(200)
+ .body("ecrRepositoryPrefix", equalTo(prefix))
+ .body("createdAt", notNullValue());
+ }
+
+ given()
+ .header("X-Amz-Target", PREFIX + "DeletePullThroughCacheRule")
+ .contentType(CT)
+ .body("""
+ { "ecrRepositoryPrefix": "%s" }
+ """.formatted(CACHE_PREFIX))
+ .when()
+ .post("/")
+ .then()
+ .statusCode(400)
+ .body("__type", equalTo("PullThroughCacheRuleNotFoundException"));
+ }
}
diff --git a/src/test/java/io/github/hectorvent/floci/services/ecr/EcrServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/ecr/EcrServiceTest.java
index 2d27dcb6a5..a581db4465 100644
--- a/src/test/java/io/github/hectorvent/floci/services/ecr/EcrServiceTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/ecr/EcrServiceTest.java
@@ -2,6 +2,7 @@ package io.github.hectorvent.floci.services.ecr;
import io.github.hectorvent.floci.config.EmulatorConfig;
import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
import io.github.hectorvent.floci.core.common.RegionResolver;
import io.github.hectorvent.floci.core.storage.AccountAwareStorageBackend;
import io.github.hectorvent.floci.core.storage.InMemoryStorage;
@@ -9,6 +10,7 @@ import io.github.hectorvent.floci.services.ecr.model.ImageDetail;
import io.github.hectorvent.floci.services.ecr.model.ImageIdentifier;
import io.github.hectorvent.floci.services.ecr.model.AuthorizationData;
import io.github.hectorvent.floci.services.ecr.model.ImageMetadata;
+import io.github.hectorvent.floci.services.ecr.model.PullThroughCacheRule;
import io.github.hectorvent.floci.services.ecr.model.Repository;
import io.github.hectorvent.floci.services.ecr.registry.EcrRegistryManager;
import io.github.hectorvent.floci.services.ecr.registry.RegistryHttpClient;
@@ -23,6 +25,7 @@ import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.util.Base64;
+import java.util.Collections;
import java.util.List;
import java.util.Map;
@@ -46,6 +49,7 @@ class EcrServiceTest {
private EcrService service;
private EcrRegistryManager registryManager;
+ private InMemoryStorage<String, PullThroughCacheRule> pullThroughCacheRuleStore;
@BeforeEach
void setUp() {
@@ -62,15 +66,140 @@ class EcrServiceTest {
EmulatorConfig config = Mockito.mock(EmulatorConfig.class);
RegionResolver regionResolver = new RegionResolver(REGION, ACCOUNT);
+ pullThroughCacheRuleStore = new InMemoryStorage<>();
service = new EcrService(
new InMemoryStorage<>(),
new InMemoryStorage<>(),
+ pullThroughCacheRuleStore,
registryManager,
config,
regionResolver);
}
+ // ------------------------------------------------------------
+ // Pull through cache rules
+ // ------------------------------------------------------------
+
+ @Test
+ void createPullThroughCacheRule_roundTripsDefaults() {
+ PullThroughCacheRule rule = service.createPullThroughCacheRule(
+ "docker-hub/", "registry-1.docker.io", null, null,
+ null, null, null, REGION);
+
+ assertEquals("docker-hub", rule.getEcrRepositoryPrefix());
+ assertEquals("registry-1.docker.io", rule.getUpstreamRegistryUrl());
+ assertEquals("docker-hub", rule.getUpstreamRegistry());
+ assertEquals("ROOT", rule.getUpstreamRepositoryPrefix());
+ assertEquals(ACCOUNT, rule.getRegistryId());
+ assertNotNull(rule.getCreatedAt());
+ assertEquals(rule.getCreatedAt(), rule.getUpdatedAt());
+ }
+
+ @Test
+ void createPullThroughCacheRule_duplicate_throwsAlreadyExists() {
+ service.createPullThroughCacheRule("docker-hub", "registry-1.docker.io", null,
+ null, null, null, null, REGION);
+
+ AwsException exception = assertThrows(AwsException.class,
+ () -> service.createPullThroughCacheRule("docker-hub/", "registry-1.docker.io", null,
+ null, null, null, null, REGION));
+
+ assertEquals("PullThroughCacheRuleAlreadyExistsException", exception.getErrorCode());
+ }
+
+ @Test
+ void describePullThroughCacheRules_filtersAndPaginates() {
+ service.createPullThroughCacheRule("cache/alpha", "registry-1.docker.io", null,
+ "docker-hub", null, null, "library", REGION);
+ service.createPullThroughCacheRule("cache/beta", "quay.io", null,
+ null, null, null, null, REGION);
+ service.createPullThroughCacheRule("cache/gamma", "registry.k8s.io", null,
+ null, null, null, null, REGION);
+
+ PaginatedResult<PullThroughCacheRule> first = service.describePullThroughCacheRules(
+ null, null, 1, null, REGION);
+ PaginatedResult<PullThroughCacheRule> second = service.describePullThroughCacheRules(
+ null, null, 1, first.nextToken(), REGION);
+ PaginatedResult<PullThroughCacheRule> filtered = service.describePullThroughCacheRules(
+ null, List.of("cache/gamma/"), null, null, REGION);
+
+ assertEquals("cache/alpha", first.items().getFirst().getEcrRepositoryPrefix());
+ assertNotNull(first.nextToken());
+ assertEquals("cache/beta", second.items().getFirst().getEcrRepositoryPrefix());
+ assertEquals("cache/gamma", filtered.items().getFirst().getEcrRepositoryPrefix());
+ }
+
+ @Test
+ void pullThroughCacheRules_areIsolatedByAccountAndRegion() {
+ String otherAccount = "111111111111";
+ service.createPullThroughCacheRule("shared/cache", "quay.io", null,
+ null, null, null, null, REGION);
+ service.createPullThroughCacheRule("shared/cache", "registry.k8s.io", otherAccount,
+ null, null, null, null, REGION);
+ service.createPullThroughCacheRule("shared/cache", "ghcr.io", null,
+ null, null, null, null, "eu-west-1");
+
+ assertEquals("quay.io", service.describePullThroughCacheRules(
+ null, null, null, null, REGION).items().getFirst().getUpstreamRegistryUrl());
+ assertEquals("registry.k8s.io", service.describePullThroughCacheRules(
+ otherAccount, null, null, null, REGION).items().getFirst().getUpstreamRegistryUrl());
+ assertEquals("ghcr.io", service.describePullThroughCacheRules(
+ null, null, null, null, "eu-west-1").items().getFirst().getUpstreamRegistryUrl());
+ }
+
+ @Test
+ void pullThroughCacheRule_persistsAcrossServiceInstances() {
+ service.createPullThroughCacheRule("persisted/cache", "quay.io", null,
+ null, null, null, null, REGION);
+ EcrService restored = new EcrService(
+ new InMemoryStorage<>(),
+ new InMemoryStorage<>(),
+ pullThroughCacheRuleStore,
+ registryManager,
+ Mockito.mock(EmulatorConfig.class),
+ new RegionResolver(REGION, ACCOUNT));
+
+ PullThroughCacheRule rule = restored.describePullThroughCacheRules(
+ null, List.of("persisted/cache"), null, null, REGION).items().getFirst();
+
+ assertEquals("quay.io", rule.getUpstreamRegistryUrl());
+ }
+
+ @Test
+ void deletePullThroughCacheRule_removesRuleAndMissingFails() {
+ service.createPullThroughCacheRule("delete/cache", "quay.io", null,
+ null, null, null, null, REGION);
+
+ PullThroughCacheRule deleted = service.deletePullThroughCacheRule("delete/cache/", null, REGION);
+
+ assertEquals("delete/cache", deleted.getEcrRepositoryPrefix());
+ AwsException exception = assertThrows(AwsException.class,
+ () -> service.deletePullThroughCacheRule("delete/cache", null, REGION));
+ assertEquals("PullThroughCacheRuleNotFoundException", exception.getErrorCode());
+ }
+
+ @Test
+ void pullThroughCacheRule_rejectsInvalidInputs() {
+ assertEquals("InvalidParameterException", assertThrows(AwsException.class,
+ () -> service.createPullThroughCacheRule("A", "quay.io", null,
+ null, null, null, null, REGION)).getErrorCode());
+ assertEquals("UnsupportedUpstreamRegistryException", assertThrows(AwsException.class,
+ () -> service.createPullThroughCacheRule("invalid/upstream", "example.com", null,
+ null, null, null, null, REGION)).getErrorCode());
+ assertEquals("InvalidParameterException", assertThrows(AwsException.class,
+ () -> service.createPullThroughCacheRule("ROOT", "quay.io", null,
+ null, null, null, "team", REGION)).getErrorCode());
+ assertEquals("InvalidParameterException", assertThrows(AwsException.class,
+ () -> service.describePullThroughCacheRules(
+ null, List.of(), null, null, REGION)).getErrorCode());
+ assertEquals("InvalidParameterException", assertThrows(AwsException.class,
+ () -> service.describePullThroughCacheRules(
+ null, Collections.nCopies(101, "cache"), null, null, REGION)).getErrorCode());
+ assertEquals("InvalidParameterException", assertThrows(AwsException.class,
+ () -> service.describePullThroughCacheRules(null, null, 0, null, REGION)).getErrorCode());
+ }
+
// ------------------------------------------------------------
// CreateRepository
// ------------------------------------------------------------
@@ -366,6 +495,7 @@ class EcrServiceTest {
EcrService accountAwareService = new EcrService(
repositories,
new InMemoryStorage<>(),
+ new InMemoryStorage<>(),
registryManager,
Mockito.mock(EmulatorConfig.class),
new RegionResolver(REGION, ACCOUNT));