Add support for registries mirror

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

Author: jonesbusy

src/main/java/land/oras/ContainerRef.java

@@ -25,6 +25,7 @@
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import land.oras.exception.OrasException;
@@ -506,12 +507,17 @@ public ContainerRef forRegistry(String registry) {
     public boolean isInsecure(Registry registry) {
         String effectiveRegistry = getEffectiveRegistry(registry);
         ContainerRef effectiveRef = forRegistry(effectiveRegistry);
-        if (registry.getRegistriesConf().isInsecure(effectiveRef)) {
-            LOG.debug(
-                    "Access to container reference {} is insecure by location configuration for registry {}",
-                    this,
-                    effectiveRegistry);
-            return true;
+        // Config is authoritative when explicitly set (true or false).
+        // This allows a config entry with insecure=false to downgrade an otherwise-insecure registry.
+        Optional<Boolean> configured = registry.getRegistriesConf().getInsecure(effectiveRef);
+        if (configured.isPresent()) {
+            if (Boolean.TRUE.equals(configured.get())) {
+                LOG.debug(
+                        "Access to container reference {} is insecure by location configuration for registry {}",
+                        this,
+                        effectiveRegistry);
+            }
+            return Boolean.TRUE.equals(configured.get());
         }
         return registry.isInsecure();
     }

src/main/java/land/oras/Registry.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,69 @@ public ContainerRef rewrite(ContainerRef ref) {
         return ContainerRef.parse(rewrittenRefString);
     }
 
+    /**
+     * Return the explicitly configured insecure value for the registry matching the given reference.
+     * Returns empty when no matching entry exists or the field is not set (null), allowing callers
+     * to distinguish "config says false" from "config has no opinion".
+     * @param ref the container reference to look up.
+     * @return Optional of true/false when explicitly configured, empty otherwise.
+     */
+    public Optional<Boolean> getInsecure(ContainerRef ref) {
+        return selectMatchingTable(ref).map(RegistryConfig::insecure);
+    }
+
+    /**
+     * 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;
+        }
+        // Strip trailing slashes to prevent double-slash segments in the rewritten ref
+        mirrorLocation = mirrorLocation.replaceAll("/+$", "");
+        if (mirrorLocation.isBlank()) {
+            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/main/java/land/oras/auth/RegistriesConf.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());
         }
     }
 }