Add unqualified flag on container ref (#397)

Author: jonesbusy

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

@@ -69,17 +69,29 @@ public final class ContainerRef extends Ref<ContainerRef> {
      */
     private final @Nullable String digest;
 
+    /**
+     * Whether the container reference is unqualified without registry
+     */
+    private final boolean unqualified;
+
     /**
      * Private constructor
      * @param registry The registry where the container is stored.
+     * @param unqualified Whether the container reference is unqualified without registry
      * @param namespace The namespace of the container.
      * @param repository The repository where the container is stored
      * @param tag The tag of the container.
      * @param digest The digest of the container.
      */
     private ContainerRef(
-            String registry, @Nullable String namespace, String repository, String tag, @Nullable String digest) {
+            String registry,
+            boolean unqualified,
+            @Nullable String namespace,
+            String repository,
+            String tag,
+            @Nullable String digest) {
         super(tag);
+        this.unqualified = unqualified;
         this.registry = registry;
         this.namespace = namespace;
         this.repository = repository;
@@ -94,6 +106,28 @@ public String getRegistry() {
         return registry;
     }
 
+    /**
+     * Get the effective registry based on given target
+     * @param target The target registry
+     * @return The effective registry
+     */
+    public String getEffectiveRegistry(Registry target) {
+        if (isUnqualified()) {
+            if (target.getRegistry() != null) {
+                return target.getRegistry();
+            }
+        }
+        return registry;
+    }
+
+    /**
+     * Whether the container reference is unqualified without registry
+     * @return True if unqualified
+     */
+    public boolean isUnqualified() {
+        return unqualified;
+    }
+
     /**
      * Get the full repository name including the namespace if any
      * @param registry The registry
@@ -181,7 +215,7 @@ public String getRepository() {
 
     @Override
     public ContainerRef withDigest(String digest) {
-        return new ContainerRef(registry, namespace, repository, tag, digest);
+        return new ContainerRef(registry, unqualified, namespace, repository, tag, digest);
     }
 
     @Override
@@ -329,11 +363,13 @@ public static ContainerRef parse(String name) {
         String repository = matcher.group(3);
         String tag = matcher.group(4);
         String digest = matcher.group(5);
+        boolean unqualified = false;
         if (repository == null) {
             throw new IllegalArgumentException("You are minimally required to include a <namespace>/<repository>");
         }
         if (registry == null) {
             registry = Const.DEFAULT_REGISTRY;
+            unqualified = true;
         }
         if (tag == null) {
             tag = Const.DEFAULT_TAG;
@@ -348,7 +384,7 @@ public static ContainerRef parse(String name) {
             SupportedAlgorithm.fromDigest(digest);
         }
 
-        return new ContainerRef(registry, namespace, repository, tag, digest);
+        return new ContainerRef(registry, unqualified, namespace, repository, tag, digest);
     }
 
     /**
@@ -357,7 +393,7 @@ public static ContainerRef parse(String name) {
      * @return The container reference
      */
     public ContainerRef forRegistry(String registry) {
-        return new ContainerRef(registry, namespace, repository, tag, digest);
+        return new ContainerRef(registry, false, namespace, repository, tag, digest);
     }
 
     /**
@@ -368,6 +404,7 @@ public ContainerRef forRegistry(String registry) {
     public ContainerRef forRegistry(Registry registry) {
         return new ContainerRef(
                 registry.getRegistry() != null ? registry.getRegistry() : this.registry,
+                false, // not unqualified if registry is set
                 namespace,
                 repository,
                 tag,

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

@@ -597,6 +597,23 @@ public Descriptor probeDescriptor(ContainerRef ref) {
         return Descriptor.of(digest, 0L, contentType);
     }
 
+    /**
+     * Return if the container ref manifests or index exists
+     * @param containerRef The container
+     * @return True if exists
+     */
+    boolean exists(ContainerRef containerRef) {
+        URI uri = URI.create(
+                "%s://%s".formatted(getScheme(), containerRef.forRegistry(this).getManifestsPath(this)));
+        HttpClient.ResponseWrapper<String> response = client.head(
+                uri,
+                Map.of(Const.ACCEPT_HEADER, Const.MANIFEST_ACCEPT_TYPE),
+                Scopes.of(this, containerRef),
+                authProvider);
+        logResponse(response);
+        return response.statusCode() == 200;
+    }
+
     /**
      * Get a manifest response
      * @param containerRef The container

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

@@ -50,12 +50,6 @@ public class AuthStore {
      */
     private final Config config;
 
-    /**
-     * Error message indicating that the format of the provided credential is invalid.
-     * This is typically used when credentials do not match the expected structure or format.
-     */
-    public static final String ERR_BAD_CREDENTIAL_FORMAT = "Bad credential format";
-
     /**
      * Constructor for FileStore.
      *

src/main/java/land/oras/utils/Const.java

@@ -39,7 +39,7 @@ private Const() {
     }
 
     /**
-     * Default registry
+     * Default registry when no unqualified-search-registries is set in the config
      */
     public static final String DEFAULT_REGISTRY = "docker.io";
 

src/test/java/land/oras/ContainerRefTest.java

@@ -37,6 +37,7 @@ void shouldReturnWithDigest() {
         // Explicit
         ContainerRef containerRef1 = ContainerRef.parse("docker.io/library/foo");
         ContainerRef withDigest1 = containerRef1.withDigest("sha256@12344");
+        assertFalse(containerRef1.isUnqualified(), "ContainerRef must be qualified");
         assertEquals("sha256@12344", withDigest1.getDigest());
         assertEquals("library", withDigest1.getNamespace());
         assertEquals(
@@ -159,6 +160,7 @@ void shouldParseImageWithNoDigest() {
     @Test
     void shouldParseImageWithNoRegistry() {
         ContainerRef containerRef = ContainerRef.parse("alpine:latest");
+        assertTrue(containerRef.isUnqualified(), "ContainerRef must be unqualified");
         assertEquals("docker.io", containerRef.getRegistry());
         assertEquals("registry-1.docker.io", containerRef.getApiRegistry());
         assertEquals(
@@ -171,12 +173,20 @@ void shouldParseImageWithNoRegistry() {
         assertEquals("alpine", containerRef.getRepository());
         assertEquals("latest", containerRef.getTag());
         assertNull(containerRef.getDigest());
+        assertFalse(containerRef.forRegistry("docker.io").isUnqualified(), "ContainerRef must be qualified");
     }
 
     @Test
     void shouldParseImageWithNoTagAndNoRegistry() {
         ContainerRef containerRef = ContainerRef.parse("alpine");
         assertEquals("docker.io", containerRef.getRegistry());
+        assertEquals(
+                "docker.io",
+                containerRef.getEffectiveRegistry(Registry.builder().build()));
+        assertEquals(
+                "my-registry.com",
+                containerRef.getEffectiveRegistry(
+                        Registry.builder().withRegistry("my-registry.com").build()));
         assertEquals("library", containerRef.getNamespace());
         assertEquals(
                 "library/alpine",

src/test/java/land/oras/RegistryTest.java

@@ -693,6 +693,8 @@ void testShouldPushAndPullMinimalArtifact() throws IOException {
                 .build();
         ContainerRef containerRef =
                 ContainerRef.parse("%s/library/artifact-full".formatted(this.registry.getRegistry()));
+        ContainerRef unknown =
+                ContainerRef.parse("%s/library/artifact-full:unknown".formatted(this.registry.getRegistry()));
 
         Path file1 = blobDir.resolve("file1.txt");
         Files.writeString(file1, "foobar");
@@ -703,6 +705,9 @@ void testShouldPushAndPullMinimalArtifact() throws IOException {
         assertEquals(
                 Const.DEFAULT_ARTIFACT_MEDIA_TYPE, manifest.getArtifactType().getMediaType());
 
+        assertTrue(registry.exists(containerRef), "Artifact should exist");
+        assertFalse(registry.exists(unknown), "Artifact should not exist");
+
         // Ensure one annotation (created by the SDK)
         Map<String, String> manifestAnnotations = manifest.getAnnotations();
         assertEquals(1, manifestAnnotations.size(), "Annotations size is incorrect");

src/test/resources/junit-platform.properties

@@ -1,2 +1,4 @@
 junit.jupiter.execution.parallel.enabled=true
 junit.jupiter.execution.parallel.mode.classes.default=concurrent
+junit.jupiter.execution.parallel.config.strategy=fixed
+junit.jupiter.execution.parallel.config.fixed.parallelism=5