refactor: extract canMount to OCI, remove instanceof from CopyUtils, getBlobsMountPath takes ContainerRef, OCILayout.mountBlob throws on missing source

- Add abstract boolean canMount(OCI<?> other) to OCI<T>
- Registry.canMount: true when source is also a Registry
- OCILayout.canMount: true when source is also an OCILayout
- OCILayout.mountBlob now throws OrasException when source blob not found (void-like)
- ContainerRef.getBlobsMountPath now takes ContainerRef instead of String
- CopyUtils: add private canMount() helper delegating to OCI.canMount
- CopyUtils: tryMountBlob no longer references Registry/OCILayout/ContainerRef/LayoutRef
- Update OCILayout tests for new exception-based behavior

Co-authored-by: jonesbusy <[email protected]>

Author: Copilot

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

@@ -380,15 +380,16 @@ public String getBlobsUploadPath(Registry registry) {
     /**
      * Return the blobs mount URL for cross-repository blob mounting
      * @param registry The registry
-     * @param sourceRepository The source repository to mount the blob from
+     * @param sourceRef The source container reference to mount the blob from
      * @return The blobs mount URL
      */
-    public String getBlobsMountPath(Registry registry, String sourceRepository) {
+    public String getBlobsMountPath(Registry registry, ContainerRef sourceRef) {
         if (digest == null) {
             throw new OrasException("You are required to include a digest");
         }
         return "%s/blobs/uploads/?mount=%s&from=%s".formatted(
-                getApiPrefix(registry), digest, URLEncoder.encode(sourceRepository, StandardCharsets.UTF_8));
+                getApiPrefix(registry), digest,
+                URLEncoder.encode(sourceRef.getFullRepository(registry), StandardCharsets.UTF_8));
     }
 
     /**

src/main/java/land/oras/CopyUtils.java

@@ -286,8 +286,7 @@ void copyConfig(
 
     /**
      * Attempt to mount a blob from source to target without downloading and re-uploading.
-     * Mounting is only attempted when source and target are the same OCI type and,
-     * for registries, when they share the same registry host.
+     * Mounting is only attempted when {@link #canMount(OCI, OCI)} returns {@code true}.
      * @param source The source OCI
      * @param sourceRef The source reference
      * @param target The target OCI
@@ -307,29 +306,24 @@ boolean tryMountBlob(
                     OCI<TargetRefType> target,
                     TargetRefType targetRef,
                     String digest) {
-        // Registry-to-Registry mounting: only when pointing at the same registry host
-        if (source instanceof Registry sourceRegistry && target instanceof Registry targetRegistry) {
-            ContainerRef srcRef = (ContainerRef) sourceRef;
-            ContainerRef tgtRef = (ContainerRef) targetRef;
-            String sourceApiRegistry = srcRef.getApiRegistry(sourceRegistry);
-            String targetApiRegistry = tgtRef.getApiRegistry(targetRegistry);
-            if (sourceApiRegistry.equals(targetApiRegistry)) {
-                ContainerRef layerSrcRef = srcRef.withDigest(digest);
-                ContainerRef layerTgtRef = tgtRef.withDigest(digest);
-                LOG.debug("Attempting mount of {} from {} to {}", digest, srcRef.getFullRepository(),
-                        tgtRef.getFullRepository());
-                return targetRegistry.mountBlob(layerTgtRef, layerSrcRef);
-            }
-        }
-        // OCILayout-to-OCILayout mounting: direct file copy between layouts
-        if (source instanceof OCILayout && target instanceof OCILayout targetLayout) {
-            LayoutRef srcRef = (LayoutRef) sourceRef;
-            LayoutRef tgtRef = (LayoutRef) targetRef;
-            LayoutRef layerSrcRef = srcRef.withDigest(digest);
-            LayoutRef layerTgtRef = tgtRef.withDigest(digest);
-            LOG.debug("Attempting mount of {} from {} to {}", digest, srcRef.getFolder(), tgtRef.getFolder());
-            return targetLayout.mountBlob(layerTgtRef, layerSrcRef);
+        if (!canMount(source, target)) {
+            return false;
         }
-        return false;
+        // canMount guarantees source and target are the same OCI type, so the cast is safe
+        TargetRefType sourceDigestRef = (TargetRefType) sourceRef.withDigest(digest);
+        LOG.debug("Attempting mount of {} from {} to {}", digest, sourceRef.getRepository(), targetRef.getRepository());
+        return target.mountBlob(targetRef.withDigest(digest), sourceDigestRef);
+    }
+
+    /**
+     * Return whether mounting is supported between the given source and target OCI instances.
+     * This delegates to {@link OCI#canMount(OCI)} on the target so that each OCI implementation
+     * defines its own compatibility rules without {@link CopyUtils} needing to know about concrete types.
+     * @param source The source OCI instance
+     * @param target The target OCI instance
+     * @return {@code true} if the target supports mounting blobs from the source
+     */
+    private static boolean canMount(OCI<?> source, OCI<?> target) {
+        return target.canMount(source);
     }
 }

src/main/java/land/oras/OCI.java

@@ -400,6 +400,15 @@ public abstract Manifest pushArtifact(
      */
     public abstract boolean mountBlob(T targetRef, T sourceRef);
 
+    /**
+     * Return whether this OCI instance supports mounting blobs from the given source OCI instance.
+     * Implementations should return {@code true} only when mounting is viable, e.g. both are
+     * registries sharing the same host, or both are OCI layouts on the local filesystem.
+     * @param other The source OCI instance to check compatibility with
+     * @return {@code true} if mounting from {@code other} is supported
+     */
+    public abstract boolean canMount(OCI<?> other);
+
     /**
      * Get the referrers of a container
      * @param ref The ref

src/main/java/land/oras/OCILayout.java

@@ -350,8 +350,7 @@ public boolean mountBlob(LayoutRef targetRef, LayoutRef sourceRef) {
                 .resolve(algorithm.getPrefix())
                 .resolve(SupportedAlgorithm.getDigest(digest));
         if (!Files.exists(sourceBlobPath)) {
-            LOG.info("Source blob not found at {}, upload required", sourceBlobPath);
-            return false;
+            throw new OrasException("Source blob not found at: %s".formatted(sourceBlobPath));
         }
         try {
             Files.copy(sourceBlobPath, targetBlobPath);
@@ -362,6 +361,11 @@ public boolean mountBlob(LayoutRef targetRef, LayoutRef sourceRef) {
         }
     }
 
+    @Override
+    public boolean canMount(OCI<?> other) {
+        return other instanceof OCILayout;
+    }
+
     @Override
     public Tags getTags(LayoutRef ref) {
         Index index = Index.fromPath(getIndexPath());

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

@@ -670,9 +670,8 @@ public boolean mountBlob(ContainerRef targetRef, ContainerRef sourceRef) {
             LOG.info("Blob already exists: {}", digest);
             return true;
         }
-        String sourceRepository = sourceRef.getFullRepository();
         URI uri = URI.create(
-                "%s://%s".formatted(getScheme(), ref.getBlobsMountPath(this, sourceRepository)));
+                "%s://%s".formatted(getScheme(), ref.getBlobsMountPath(this, sourceRef)));
         HttpClient.ResponseWrapper<String> response = client.post(
                 uri,
                 new byte[0],
@@ -681,17 +680,22 @@ public boolean mountBlob(ContainerRef targetRef, ContainerRef sourceRef) {
                 authProvider);
         logResponse(response);
         if (response.statusCode() == 201) {
-            LOG.info("Blob mounted successfully from {}: {}", sourceRepository, digest);
+            LOG.info("Blob mounted successfully from {}: {}", sourceRef.getFullRepository(), digest);
             return true;
         }
         if (response.statusCode() == 202) {
-            LOG.info("Mount not possible for blob {} from {}, upload required", digest, sourceRepository);
+            LOG.info("Mount not possible for blob {} from {}, upload required", digest, sourceRef.getFullRepository());
             return false;
         }
         handleError(response);
         return false;
     }
 
+    @Override
+    public boolean canMount(OCI<?> other) {
+        return other instanceof Registry;
+    }
+
     /**
      * Return if the registry contains already the blob
      * @param containerRef The container

src/test/java/land/oras/OCILayoutTest.java

@@ -1138,16 +1138,15 @@ void shouldMountBlobFromAnotherLayout() throws IOException {
         // Mount blob into target layout
         OCILayout targetLayout = OCILayout.Builder.builder().defaults(targetPath).build();
         LayoutRef targetRef = LayoutRef.of(targetLayout, digest);
-        boolean mounted = targetLayout.mountBlob(targetRef, sourceRef);
+        targetLayout.mountBlob(targetRef, sourceRef);
 
         // Assert mount succeeded
-        assertTrue(mounted, "Blob should be mounted successfully");
         assertBlobExists(targetPath, digest);
         assertBlobContent(targetPath, digest, "mount-test-content");
     }
 
     @Test
-    void shouldMountBlobReturnTrueIfAlreadyExists() {
+    void shouldMountBlobIdempotentIfAlreadyExists() {
 
         Path layoutPathDir = layoutPath.resolve("shouldMountBlobExisting");
 
@@ -1161,13 +1160,12 @@ void shouldMountBlobReturnTrueIfAlreadyExists() {
         ociLayout.pushBlob(ref, content);
         assertBlobExists(layoutPathDir, digest);
 
-        // Mounting again should return true (already exists)
-        boolean mounted = ociLayout.mountBlob(ref, ref);
-        assertTrue(mounted, "Mount should return true when blob already exists");
+        // Mounting again should be a no-op (already exists)
+        assertDoesNotThrow(() -> ociLayout.mountBlob(ref, ref));
     }
 
     @Test
-    void shouldMountBlobReturnFalseWhenSourceNotFound() {
+    void shouldThrowWhenMountingBlobWithMissingSource() {
 
         Path sourcePath = layoutPath.resolve("mountMissingSource");
         Path targetPath = layoutPath.resolve("mountMissingTarget");
@@ -1180,9 +1178,8 @@ void shouldMountBlobReturnFalseWhenSourceNotFound() {
         LayoutRef sourceRef = LayoutRef.of(sourceLayout, digest);
         LayoutRef targetRef = LayoutRef.of(targetLayout, digest);
 
-        // Mounting a non-existent blob should return false
-        boolean mounted = targetLayout.mountBlob(targetRef, sourceRef);
-        assertFalse(mounted, "Mount should return false when source blob does not exist");
+        // Mounting a non-existent blob should throw OrasException
+        assertThrows(OrasException.class, () -> targetLayout.mountBlob(targetRef, sourceRef));
         assertBlobAbsent(targetPath, digest);
     }
 }