Add support for registries mirror

Signed-off-by: Valentin Delaye <jonesbusy@users.noreply.github.com>

Author: jonesbusy

src/main/java/land/oras/Registry.java

@@ -39,6 +39,7 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.function.BiFunction;
 import java.util.function.Supplier;
 import land.oras.auth.AuthProvider;
 import land.oras.auth.AuthStoreAuthenticationProvider;
@@ -526,9 +527,16 @@ public void deleteBlob(ContainerRef containerRef) {
 
     @Override
     public void pullArtifact(ContainerRef containerRef, Path path, boolean overwrite) {
+        withMirrorFallback(containerRef, (reg, ref) -> {
+            reg.pullArtifactDirect(ref, path, overwrite);
+            return null;
+        });
+    }
+
+    private void pullArtifactDirect(ContainerRef containerRef, Path path, boolean overwrite) {
         ContainerRef ref = containerRef.forRegistry(this).checkBlocked(this);
         if (ref.isInsecure(this) && !this.isInsecure()) {
-            asInsecure().pullArtifact(containerRef, path, overwrite);
+            asInsecure().pullArtifactDirect(containerRef, path, overwrite);
             return;
         }
         // Only collect layer that are files
@@ -945,9 +953,13 @@ private HttpClient.ResponseWrapper<String> headBlob(ContainerRef containerRef) {
      */
     @Override
     public byte[] getBlob(ContainerRef containerRef) {
+        return withMirrorFallback(containerRef, (reg, ref) -> reg.getBlobDirect(ref));
+    }
+
+    private byte[] getBlobDirect(ContainerRef containerRef) {
         ContainerRef ref = containerRef.forRegistry(this).checkBlocked(this);
         if (ref.isInsecure(this) && !this.isInsecure()) {
-            return asInsecure().getBlob(containerRef);
+            return asInsecure().getBlobDirect(containerRef);
         }
         URI uri = URI.create("%s://%s".formatted(getScheme(), ref.getBlobsPath(this)));
         HttpClient.ResponseWrapper<String> response = client.get(
@@ -964,9 +976,16 @@ public byte[] getBlob(ContainerRef containerRef) {
 
     @Override
     public void fetchBlob(ContainerRef containerRef, Path path) {
+        withMirrorFallback(containerRef, (reg, ref) -> {
+            reg.fetchBlobDirect(ref, path);
+            return null;
+        });
+    }
+
+    private void fetchBlobDirect(ContainerRef containerRef, Path path) {
         ContainerRef ref = containerRef.forRegistry(this).checkBlocked(this);
         if (ref.isInsecure(this) && !this.isInsecure()) {
-            asInsecure().fetchBlob(containerRef, path);
+            asInsecure().fetchBlobDirect(containerRef, path);
             return;
         }
         URI uri = URI.create("%s://%s".formatted(getScheme(), ref.getBlobsPath(this)));
@@ -983,9 +1002,13 @@ public void fetchBlob(ContainerRef containerRef, Path path) {
 
     @Override
     public InputStream fetchBlob(ContainerRef containerRef) {
+        return withMirrorFallback(containerRef, (reg, ref) -> reg.fetchBlobDirect(ref));
+    }
+
+    private InputStream fetchBlobDirect(ContainerRef containerRef) {
         ContainerRef ref = containerRef.forRegistry(this).checkBlocked(this);
         if (ref.isInsecure(this) && !this.isInsecure()) {
-            return asInsecure().fetchBlob(containerRef);
+            return asInsecure().fetchBlobDirect(containerRef);
         }
         URI uri = URI.create("%s://%s".formatted(getScheme(), ref.getBlobsPath(this)));
         HttpClient.ResponseWrapper<InputStream> response = client.download(
@@ -1106,14 +1129,54 @@ boolean exists(ContainerRef containerRef) {
     }
 
     /**
-     * Get a manifest response
+     * Execute an operation with mirror fallback. Mirrors are tried in order; if all fail the
+     * operation is retried against the original registry.
+     * @param containerRef The original container reference used to look up mirrors
+     * @param operation A function (registry, ref) → result; called for each candidate
+     * @return The result from the first successful invocation
+     */
+    private <T> T withMirrorFallback(ContainerRef containerRef, BiFunction<Registry, ContainerRef, T> operation) {
+        List<RegistriesConf.MirrorConfig> mirrors = registriesConf.getMirrors(containerRef);
+        for (RegistriesConf.MirrorConfig mirror : mirrors) {
+            String mirrorLocation = mirror.location();
+            if (mirrorLocation == null || mirrorLocation.isBlank()) continue;
+            ContainerRef mirrorRef = registriesConf.rewriteForMirror(containerRef, mirror);
+            // Use only the host[:port] for copy() — the path prefix is already baked into mirrorRef
+            // by rewriteForMirror, so including it here would double-apply the path.
+            // Strip any scheme (e.g., "https://") before extracting the host.
+            String locationNoScheme = mirrorLocation.contains("://")
+                    ? mirrorLocation.substring(mirrorLocation.indexOf("://") + 3)
+                    : mirrorLocation;
+            String mirrorHost = locationNoScheme.contains("/")
+                    ? locationNoScheme.substring(0, locationNoScheme.indexOf('/'))
+                    : locationNoScheme;
+            Registry mirrorRegistry = copy(mirrorHost);
+            if (mirror.isInsecure() && !isInsecure()) {
+                mirrorRegistry = mirrorRegistry.asInsecure();
+            }
+            try {
+                LOG.debug("Trying mirror {} for {}", mirrorLocation, containerRef);
+                return operation.apply(mirrorRegistry, mirrorRef);
+            } catch (OrasException e) {
+                LOG.warn("Mirror {} failed for {}: {}", mirrorLocation, containerRef, e.getMessage());
+            }
+        }
+        return operation.apply(this, containerRef);
+    }
+
+    /**
+     * Get a manifest response, trying configured mirrors before the original registry.
      * @param containerRef The container
      * @return The response
      */
     private HttpClient.ResponseWrapper<String> getManifestResponse(ContainerRef containerRef) {
+        return withMirrorFallback(containerRef, (reg, ref) -> reg.getManifestResponseDirect(ref));
+    }
+
+    private HttpClient.ResponseWrapper<String> getManifestResponseDirect(ContainerRef containerRef) {
         ContainerRef ref = containerRef.forRegistry(this).checkBlocked(this);
         if (ref.isInsecure(this) && !this.isInsecure()) {
-            return asInsecure().getManifestResponse(containerRef);
+            return asInsecure().getManifestResponseDirect(containerRef);
         }
         URI uri = URI.create("%s://%s".formatted(getScheme(), ref.getManifestsPath(this)));
         HttpClient.ResponseWrapper<String> response =

src/main/java/land/oras/auth/RegistriesConf.java

@@ -99,23 +99,50 @@ public static RegistriesConf newConf() {
         return newConf(paths);
     }
 
+    /**
+     * The model of a mirror entry within a [[registry]] table.
+     * @param location The mirror registry location (host[:port][/path]).
+     * @param insecure Whether the mirror is insecure.
+     */
+    @OrasModel
+    public record MirrorConfig(
+            @Nullable @JsonProperty("location") String location, @Nullable @JsonProperty("insecure") Boolean insecure) {
+        /**
+         * Return true if this mirror should be accessed over plain HTTP or with unverified TLS.
+         * @return true if insecure
+         */
+        public boolean isInsecure() {
+            return insecure != null && insecure;
+        }
+    }
+
     /**
      * The model of the registry configuration
      * @param prefix The prefix to match against container references.
      * @param location The registry location
      * @param blocked Whether the registry is blocked. If true, the registry is blocked and cannot be used for pulling or pushing images.
      * @param insecure Whether the registry is insecure. If true, the registry is considered insecure and may allow connections over HTTP or with invalid TLS certificates.
+     * @param mirrors Ordered list of mirror entries to try before the registry location.
      */
     @OrasModel
     record RegistryConfig(
             @Nullable @JsonProperty("prefix") String prefix,
             @Nullable @JsonProperty("location") String location,
             @Nullable @JsonProperty("blocked") Boolean blocked,
-            @Nullable @JsonProperty("insecure") Boolean insecure) {
+            @Nullable @JsonProperty("insecure") Boolean insecure,
+            @Nullable @JsonProperty("mirror") List<MirrorConfig> mirrors) {
+        /**
+         * Return true if this registry is blocked and cannot be used for pulling or pushing images.
+         * @return true if blocked
+         */
         public boolean isBlocked() {
             return blocked != null && blocked;
         }
 
+        /**
+         * Return true if this registry should be accessed over plain HTTP or with unverified TLS.
+         * @return true if insecure
+         */
         public boolean isInsecure() {
             return insecure != null && insecure;
         }
@@ -333,6 +360,56 @@ public ContainerRef rewrite(ContainerRef ref) {
         return ContainerRef.parse(rewrittenRefString);
     }
 
+    /**
+     * Return the ordered list of mirrors configured for the registry that matches the given reference.
+     * @param ref the container reference to look up mirrors for.
+     * @return an unmodifiable list of mirror configs (may be empty).
+     */
+    public List<MirrorConfig> getMirrors(ContainerRef ref) {
+        Optional<RegistryConfig> matchingConfig = selectMatchingTable(ref);
+        if (matchingConfig.isEmpty() || matchingConfig.get().mirrors() == null) {
+            return Collections.emptyList();
+        }
+        return Collections.unmodifiableList(matchingConfig.get().mirrors());
+    }
+
+    /**
+     * Rewrite the given container reference to use the mirror's location, replacing the registry host.
+     * @param ref the original container reference.
+     * @param mirror the mirror configuration to apply.
+     * @return the rewritten reference pointing at the mirror.
+     */
+    public ContainerRef rewriteForMirror(ContainerRef ref, MirrorConfig mirror) {
+        String mirrorLocation = mirror.location();
+        if (mirrorLocation == null || mirrorLocation.isBlank()) {
+            return ref;
+        }
+        if (!ref.isUnqualified() && ref.getRegistry() == null) {
+            return ref;
+        }
+        // Always build from components to correctly handle:
+        // - unqualified refs (toString() omits the registry)
+        // - digest-only refs (tag is null, toString() would produce ":null")
+        String namespace = ref.getNamespace();
+        String repository = ref.getRepository();
+        String tag = ref.getTag();
+        String digest = ref.getDigest();
+        StringBuilder sb = new StringBuilder(mirrorLocation);
+        if (namespace != null && !namespace.isEmpty()) {
+            sb.append("/").append(namespace);
+        }
+        sb.append("/").append(repository);
+        if (tag != null && !tag.isEmpty()) {
+            sb.append(":").append(tag);
+        }
+        if (digest != null && !digest.isEmpty()) {
+            sb.append("@").append(digest);
+        }
+        String rewrittenRefString = sb.toString();
+        LOG.debug("Rewriting '{}' to mirror '{}'", ref, rewrittenRefString);
+        return ContainerRef.parse(rewrittenRefString);
+    }
+
     /**
      * Select the matching registry configuration table for the container reference.
      * @param ref the container reference to find the matching registry configuration for.

src/test/java/land/oras/ClassAnnotationsTest.java

@@ -49,7 +49,7 @@ void shouldHaveAnnotationOnModel() {
                     .loadClasses());
 
             // Check number of classes
-            assertEquals(26, modelClasses.size());
+            assertEquals(27, modelClasses.size());
 
             // Check classes
             assertTrue(modelClasses.contains(Annotations.class));
@@ -83,7 +83,7 @@ void shouldHaveAnnotationOnAuthPackage() {
                     .loadClasses());
 
             // Check number of classes
-            assertEquals(8, modelClasses.size());
+            assertEquals(9, modelClasses.size());
         }
     }
 }