feat: add blob mounting support for Registry and OCILayout

Copilot · jonesbusy · Copilot · commit 2a70b02e4994 · 2026-03-14T13:02:39.000Z
- Add getBlobsMountPath() to ContainerRef for mount URL construction
- Add abstract mountBlob() method to OCI base class
- Implement mountBlob() in Registry using POST /v2/&lt;name&gt;/blobs/uploads/?mount=&lt;digest&gt;&amp;from=&lt;other_name&gt;
- Implement mountBlob() in OCILayout using direct file copy
- Update CopyUtils to attempt mounting when copying between same-type OCI on same registry
- Add tests for mountBlob in RegistryTest and OCILayoutTest

Co-authored-by: jonesbusy &lt;825750+jonesbusy@users.noreply.github.com&gt;
diff --git a/REPOSITORY_ANALYSIS.md b/REPOSITORY_ANALYSIS.md
diff --git a/src/main/java/land/oras/ContainerRef.java b/src/main/java/land/oras/ContainerRef.java
@@ -377,6 +377,20 @@ public String getBlobsUploadPath(Registry registry) {
         return "%s/blobs/uploads/".formatted(getApiPrefix(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
+     * @return The blobs mount URL
+     */
+    public String getBlobsMountPath(Registry registry, String sourceRepository) {
+        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));
+    }
+
     /**
      * Return the blobs URL
      * @param registry The registry
diff --git a/src/main/java/land/oras/CopyUtils.java b/src/main/java/land/oras/CopyUtils.java
@@ -113,11 +113,16 @@ void copyLayers(
                             Objects.requireNonNull(layer.getDigest(), "Layer digest is required for streaming copy");
                             Objects.requireNonNull(layer.getSize(), "Layer size is required for streaming copy");
                             return CompletableFuture.runAsync(
-                                    () -> target.pushBlob(
-                                            targetRef.withDigest(layer.getDigest()),
-                                            layer.getSize(),
-                                            () -> source.fetchBlob(sourceRef.withDigest(layer.getDigest())),
-                                            layer.getAnnotations()),
+                                    () -> {
+                                        if (!tryMountBlob(source, sourceRef, target, targetRef, layer.getDigest())) {
+                                            target.pushBlob(
+                                                    targetRef.withDigest(layer.getDigest()),
+                                                    layer.getSize(),
+                                                    () -> source.fetchBlob(
+                                                            sourceRef.withDigest(layer.getDigest())),
+                                                    layer.getAnnotations());
+                                        }
+                                    },
                                     source.getExecutorService());
                         })
                         .toArray(CompletableFuture[]::new))
@@ -267,11 +272,64 @@ void copyConfig(
         Config config = manifest.getConfig();
         Objects.requireNonNull(config.getDigest(), "Config digest is required for streaming copy");
         Objects.requireNonNull(config.getSize(), "Config size is required for streaming copy");
-        target.pushBlob(
-                targetRef.forTarget(target).withDigest(manifest.getConfig().getDigest()),
-                config.getSize(),
-                () -> source.pullConfig(sourceRef, manifest.getConfig()),
-                config.getAnnotations());
+        TargetRefType configTargetRef =
+                targetRef.forTarget(target).withDigest(manifest.getConfig().getDigest());
+        if (!tryMountBlob(source, sourceRef, target, targetRef, config.getDigest())) {
+            target.pushBlob(
+                    configTargetRef,
+                    config.getSize(),
+                    () -> source.pullConfig(sourceRef, manifest.getConfig()),
+                    config.getAnnotations());
+        }
         LOG.debug("Copied config {}", manifest.getConfig().getDigest());
     }
+
+    /**
+     * 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.
+     * @param source The source OCI
+     * @param sourceRef The source reference
+     * @param target The target OCI
+     * @param targetRef The target reference
+     * @param digest The digest of the blob to mount
+     * @param <SourceRefType> The source reference type
+     * @param <TargetRefType> The target reference type
+     * @return {@code true} if the blob was successfully mounted, {@code false} if a regular upload is required
+     */
+    @SuppressWarnings("unchecked")
+    private static <
+                    SourceRefType extends Ref<@NonNull SourceRefType>,
+                    TargetRefType extends Ref<@NonNull TargetRefType>>
+            boolean tryMountBlob(
+                    OCI<SourceRefType> source,
+                    SourceRefType sourceRef,
+                    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);
+        }
+        return false;
+    }
 }
diff --git a/src/main/java/land/oras/OCI.java b/src/main/java/land/oras/OCI.java
@@ -388,6 +388,18 @@ public abstract Manifest pushArtifact(
      */
     public abstract Layer pushBlob(T ref, byte[] data);
 
+    /**
+     * Mount a blob from another repository in the same OCI target.
+     * For a {@link Registry}, this uses the cross-repository blob mounting endpoint
+     * ({@code POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<other_name>}).
+     * For an {@link OCILayout}, this copies the blob from the source layout folder.
+     * @param targetRef The target reference containing the digest to mount
+     * @param sourceRef The source reference containing the source repository or layout path
+     * @return {@code true} if the blob was successfully mounted without a full upload,
+     *         {@code false} if mounting failed and a regular upload is required
+     */
+    public abstract boolean mountBlob(T targetRef, T sourceRef);
+
     /**
      * Get the referrers of a container
      * @param ref The ref
diff --git a/src/main/java/land/oras/OCILayout.java b/src/main/java/land/oras/OCILayout.java
@@ -331,6 +331,37 @@ public Layer pushBlob(LayoutRef ref, byte[] data) {
         }
     }
 
+    @Override
+    public boolean mountBlob(LayoutRef targetRef, LayoutRef sourceRef) {
+        String digest = targetRef.getTag();
+        if (digest == null || !SupportedAlgorithm.isSupported(digest)) {
+            throw new OrasException("Digest is required to mount blob");
+        }
+        ensureAlgorithmPath(digest);
+        Path targetBlobPath = getBlobPath(targetRef);
+        if (Files.exists(targetBlobPath)) {
+            LOG.info("Blob already exists: {}", digest);
+            return true;
+        }
+        // Compute source blob path from the source layout folder
+        SupportedAlgorithm algorithm = SupportedAlgorithm.fromDigest(digest);
+        Path sourceBlobPath = sourceRef.getFolder()
+                .resolve(Const.OCI_LAYOUT_BLOBS)
+                .resolve(algorithm.getPrefix())
+                .resolve(SupportedAlgorithm.getDigest(digest));
+        if (!Files.exists(sourceBlobPath)) {
+            LOG.info("Source blob not found at {}, upload required", sourceBlobPath);
+            return false;
+        }
+        try {
+            Files.copy(sourceBlobPath, targetBlobPath);
+            LOG.info("Blob mounted from {}: {}", sourceRef.getFolder(), digest);
+            return true;
+        } catch (IOException e) {
+            throw new OrasException("Failed to mount blob", e);
+        }
+    }
+
     @Override
     public Tags getTags(LayoutRef ref) {
         Index index = Index.fromPath(getIndexPath());
diff --git a/src/main/java/land/oras/Registry.java b/src/main/java/land/oras/Registry.java
@@ -656,6 +656,42 @@ public Layer pushBlob(ContainerRef containerRef, byte[] data) {
         return Layer.fromData(ref, data);
     }
 
+    @Override
+    public boolean mountBlob(ContainerRef targetRef, ContainerRef sourceRef) {
+        String digest = targetRef.getDigest();
+        if (digest == null) {
+            throw new OrasException("Digest is required to mount blob");
+        }
+        ContainerRef ref = targetRef.forRegistry(this).checkBlocked(this);
+        if (ref.isInsecure(this) && !this.isInsecure()) {
+            return asInsecure().mountBlob(targetRef, sourceRef);
+        }
+        if (hasBlob(ref)) {
+            LOG.info("Blob already exists: {}", digest);
+            return true;
+        }
+        String sourceRepository = sourceRef.getFullRepository();
+        URI uri = URI.create(
+                "%s://%s".formatted(getScheme(), ref.getBlobsMountPath(this, sourceRepository)));
+        HttpClient.ResponseWrapper<String> response = client.post(
+                uri,
+                new byte[0],
+                Map.of(Const.CONTENT_TYPE_HEADER, Const.APPLICATION_OCTET_STREAM_HEADER_VALUE),
+                Scopes.of(ref),
+                authProvider);
+        logResponse(response);
+        if (response.statusCode() == 201) {
+            LOG.info("Blob mounted successfully from {}: {}", sourceRepository, digest);
+            return true;
+        }
+        if (response.statusCode() == 202) {
+            LOG.info("Mount not possible for blob {} from {}, upload required", digest, sourceRepository);
+            return false;
+        }
+        handleError(response);
+        return false;
+    }
+
     /**
      * Return if the registry contains already the blob
      * @param containerRef The container
diff --git a/src/test/java/land/oras/OCILayoutTest.java b/src/test/java/land/oras/OCILayoutTest.java
@@ -1119,4 +1119,70 @@ private void assertBlobContent(Path ociLayoutPath, String digest, String content
                         .resolve(SupportedAlgorithm.getDigest(digest))),
                 "Expect blob content to match");
     }
+
+    @Test
+    void shouldMountBlobFromAnotherLayout() throws IOException {
+
+        Path sourcePath = layoutPath.resolve("shouldMountBlobSource");
+        Path targetPath = layoutPath.resolve("shouldMountBlobTarget");
+
+        byte[] content = "mount-test-content".getBytes(StandardCharsets.UTF_8);
+        String digest = SupportedAlgorithm.SHA256.digest(content);
+
+        // Push blob to source layout
+        OCILayout sourceLayout = OCILayout.Builder.builder().defaults(sourcePath).build();
+        LayoutRef sourceRef = LayoutRef.of(sourceLayout, digest);
+        sourceLayout.pushBlob(sourceRef, content);
+        assertBlobExists(sourcePath, digest);
+
+        // 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);
+
+        // Assert mount succeeded
+        assertTrue(mounted, "Blob should be mounted successfully");
+        assertBlobExists(targetPath, digest);
+        assertBlobContent(targetPath, digest, "mount-test-content");
+    }
+
+    @Test
+    void shouldMountBlobReturnTrueIfAlreadyExists() {
+
+        Path layoutPathDir = layoutPath.resolve("shouldMountBlobExisting");
+
+        byte[] content = "existing-blob".getBytes(StandardCharsets.UTF_8);
+        String digest = SupportedAlgorithm.SHA256.digest(content);
+
+        OCILayout ociLayout = OCILayout.Builder.builder().defaults(layoutPathDir).build();
+        LayoutRef ref = LayoutRef.of(ociLayout, digest);
+
+        // Push blob first
+        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");
+    }
+
+    @Test
+    void shouldMountBlobReturnFalseWhenSourceNotFound() {
+
+        Path sourcePath = layoutPath.resolve("mountMissingSource");
+        Path targetPath = layoutPath.resolve("mountMissingTarget");
+
+        String digest = "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
+
+        OCILayout sourceLayout = OCILayout.Builder.builder().defaults(sourcePath).build();
+        OCILayout targetLayout = OCILayout.Builder.builder().defaults(targetPath).build();
+
+        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");
+        assertBlobAbsent(targetPath, digest);
+    }
 }
diff --git a/src/test/java/land/oras/RegistryTest.java b/src/test/java/land/oras/RegistryTest.java
@@ -1863,4 +1863,51 @@ void shouldHandleLargeStreamContent() throws IOException {
         Files.delete(largeFile);
         registry.deleteBlob(containerRef.withDigest(layer.getDigest()));
     }
+
+    @Test
+    void shouldMountBlobFromAnotherRepository() {
+        Registry registry = Registry.Builder.builder()
+                .defaults("myuser", "mypass")
+                .withInsecure(true)
+                .build();
+
+        // Push a blob to source repository
+        String content = "hello-mount";
+        byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);
+        String digest = SupportedAlgorithm.SHA256.digest(contentBytes);
+        ContainerRef sourceRef = ContainerRef.parse(
+                "%s/library/mount-source@%s".formatted(this.registry.getRegistry(), digest));
+        registry.pushBlob(sourceRef, contentBytes);
+
+        // Mount the blob into a different repository on the same registry
+        ContainerRef targetRef = ContainerRef.parse(
+                "%s/library/mount-target@%s".formatted(this.registry.getRegistry(), digest));
+        boolean mounted = registry.mountBlob(targetRef, sourceRef);
+
+        // Mounting should succeed on Zot registry
+        assertTrue(mounted, "Blob should be mounted successfully");
+
+        // Verify the blob is now accessible in the target repository
+        byte[] blobContent = registry.getBlob(targetRef);
+        assertEquals(content, new String(blobContent, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    void shouldMountBlobReturnFalseWhenMountNotPossible() {
+        Registry registry = Registry.Builder.builder()
+                .defaults("myuser", "mypass")
+                .withInsecure(true)
+                .build();
+
+        // Try to mount a non-existent blob
+        String digest = "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
+        ContainerRef sourceRef = ContainerRef.parse(
+                "%s/library/nonexistent-source@%s".formatted(this.registry.getRegistry(), digest));
+        ContainerRef targetRef = ContainerRef.parse(
+                "%s/library/mount-fallback-target@%s".formatted(this.registry.getRegistry(), digest));
+
+        // Should return false when mount is not possible (source doesn't exist)
+        boolean mounted = registry.mountBlob(targetRef, sourceRef);
+        assertFalse(mounted, "Mount should fail when source blob does not exist");
+    }
 }
