Add support for tar files in OCI Layout in adition of exploded directories (#739)

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

Author: jonesbusy

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

@@ -25,6 +25,7 @@
 import java.io.InputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
 import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
@@ -33,6 +34,7 @@
 import java.util.concurrent.Executors;
 import java.util.function.Supplier;
 import land.oras.exception.OrasException;
+import land.oras.utils.ArchiveUtils;
 import land.oras.utils.Const;
 import land.oras.utils.JsonUtils;
 import land.oras.utils.SupportedAlgorithm;
@@ -54,6 +56,14 @@ public final class OCILayout extends OCI<LayoutRef> {
      */
     private Path path;
 
+    /**
+     * When non-null the layout is backed by a tar file.
+     * {@code path} then points to a temporary directory that holds the extracted contents.
+     * Every mutating operation re-packs that temporary directory back into this tar file.
+     */
+    @Nullable
+    private Path tarPath;
+
     /**
      * Private constructor
      */
@@ -96,6 +106,7 @@ public boolean mountBlob(LayoutRef sourceRef, LayoutRef targetRef) {
         } catch (IOException e) {
             throw new OrasException("Failed to mount blob", e);
         }
+        packToTar();
         return true;
     }
 
@@ -214,6 +225,7 @@ public Manifest pushManifest(LayoutRef layoutRef, Manifest manifest) {
         } catch (IOException e) {
             throw new OrasException("Failed to write manifest", e);
         }
+        packToTar();
         return manifest;
     }
 
@@ -249,6 +261,7 @@ public Index pushIndex(LayoutRef layoutRef, Index index) {
         } catch (IOException e) {
             throw new OrasException("Failed to write manifest", e);
         }
+        packToTar();
         return index;
     }
 
@@ -330,7 +343,9 @@ public Layer pushBlob(LayoutRef ref, Path blob, Map<String, String> annotations)
                 return Layer.fromFile(blobPath, ref.getAlgorithm()).withAnnotations(annotations);
             }
             Files.copy(blob, blobPath);
-            return Layer.fromFile(blobPath, ref.getAlgorithm()).withAnnotations(annotations);
+            Layer layer = Layer.fromFile(blobPath, ref.getAlgorithm()).withAnnotations(annotations);
+            packToTar();
+            return layer;
         } catch (IOException e) {
             throw new OrasException("Failed to push blob", e);
         }
@@ -357,7 +372,9 @@ public Layer pushBlob(LayoutRef ref, long size, Supplier<InputStream> stream, Ma
                 Files.copy(is, blobPath);
             }
             ensureDigest(ref, blobPath);
-            return Layer.fromFile(blobPath, ref.getAlgorithm()).withAnnotations(annotations);
+            Layer layer = Layer.fromFile(blobPath, ref.getAlgorithm()).withAnnotations(annotations);
+            packToTar();
+            return layer;
         } catch (IOException e) {
             throw new OrasException("Failed to push blob", e);
         }
@@ -406,7 +423,9 @@ public Tags getTags(LayoutRef ref, int n, @Nullable String last) {
 
     @Override
     public Repositories getRepositories() {
-        return new Repositories(List.of(path.getFileName().toString()));
+        // When tar-backed, report the tar file name rather than the temp-dir name
+        Path reportPath = tarPath != null ? tarPath : path;
+        return new Repositories(List.of(reportPath.getFileName().toString()));
     }
 
     @Override
@@ -438,6 +457,29 @@ private void setPath(Path path) {
         this.path = path;
     }
 
+    private void setTarPath(Path tarPath) {
+        this.tarPath = tarPath;
+    }
+
+    /**
+     * Re-pack the working directory back into the backing tar file.
+     * Called after every mutating operation when {@link #tarPath} is non-null.
+     */
+    private void packToTar() {
+        if (tarPath == null) {
+            return;
+        }
+        try {
+            // Pack without directory-name prefix so entries sit at the root of the tar,
+            // matching the OCI Image Layout tar format (blobs/, index.json, oci-layout …).
+            LocalPath packed = ArchiveUtils.tar(LocalPath.of(path), false);
+            // Atomically replace the backing tar file
+            Files.move(packed.getPath(), tarPath, StandardCopyOption.REPLACE_EXISTING);
+        } catch (IOException e) {
+            throw new OrasException("Failed to repack OCI layout tar: " + tarPath, e);
+        }
+    }
+
     /**
      * Return the JSON representation of the referrers
      * @return The JSON string
@@ -674,14 +716,26 @@ public static OCILayout fromLayoutIndex(Path layoutPath) {
     }
 
     /**
-     * Return the path to the OCI layout
+     * Return the path to the OCI layout working directory.
+     * <p>When the layout is tar-backed this is the temporary directory into which the tar
+     * was extracted; use {@link #getTarPath()} to obtain the path of the backing tar file.</p>
      * @return The path to the OCI layout
      */
     @JsonIgnore
     public Path getPath() {
         return path;
     }
 
+    /**
+     * Return the path to the backing tar file, or {@code null} if the layout is directory-backed.
+     * @return The tar file path, or {@code null}
+     */
+    @JsonIgnore
+    @Nullable
+    public Path getTarPath() {
+        return tarPath;
+    }
+
     /**
      * Builder for the registry
      */
@@ -697,12 +751,30 @@ private Builder() {
         }
 
         /**
-         * Return a new builder with default path
-         * @param path The path
+         * Return a new builder with default path.
+         * <p>If {@code path} ends with {@code .tar} the layout is considered to be tar-backed.
+         * When the tar file already exists it is extracted to a temporary directory; that
+         * temporary directory is used as the working {@code path} for all operations.
+         * After every mutating operation the working directory is re-packed into the original
+         * tar file.  If the tar file does not yet exist a fresh, empty layout is created in
+         * the temporary directory and packed once on the first mutation.</p>
+         * @param path The path (directory or {@code .tar} file)
          * @return The builder
          */
         public OCILayout.Builder defaults(Path path) {
-            layout.setPath(path);
+            String name = path.getFileName().toString();
+            if (name.endsWith(".tar")) {
+                // Tar-backed layout: work in a temp directory
+                Path workDir = ArchiveUtils.createTempDir();
+                if (Files.exists(path)) {
+                    // Extract existing tar into the temp working directory
+                    ArchiveUtils.untar(path, workDir);
+                }
+                layout.setPath(workDir);
+                layout.setTarPath(path);
+            } else {
+                layout.setPath(path);
+            }
             return this;
         }
 
@@ -727,6 +799,7 @@ public OCILayout build() {
                 }
             }
             layout.ensureMinimalLayout();
+            layout.packToTar();
             return layout;
         }
     }

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

@@ -165,11 +165,28 @@ public static LocalPath zip(LocalPath sourceDir) {
     }
 
     /**
-     * Create a tar.gz file from a directory
+     * Create a tar file from a directory, prefixing every entry with the source directory's own name.
+     * <p>Equivalent to calling {@link #tar(LocalPath, boolean) tar(sourceDir, true)}.</p>
      * @param sourceDir The source directory
-     * @return The path to the tar.gz file
+     * @return The local path to the temporary tar file
      */
     public static LocalPath tar(LocalPath sourceDir) {
+        return tar(sourceDir, true);
+    }
+
+    /**
+     * Create a tar file from a directory.
+     * <p>When {@code includeDirectoryName} is {@code true} (the default behaviour) every entry
+     * is prefixed with the source directory's own name, e.g. {@code mydir/blobs/sha256/...}.
+     * When {@code false}, entries are stored relative to the source directory itself, e.g.
+     * {@code blobs/sha256/...} — which is the format required by the OCI Image Layout
+     * specification when packaging a layout as a plain tar archive.</p>
+     * @param sourceDir The source directory
+     * @param includeDirectoryName {@code true} to prefix entries with the directory name,
+     *                             {@code false} for root-relative entry names
+     * @return The local path to the temporary tar file
+     */
+    public static LocalPath tar(LocalPath sourceDir, boolean includeDirectoryName) {
         Path tarFile = createTempTar();
         boolean isAbsolute = sourceDir.getPath().isAbsolute();
         try (OutputStream fos = Files.newOutputStream(tarFile);
@@ -183,8 +200,13 @@ public static LocalPath tar(LocalPath sourceDir) {
                 paths.forEach(path -> {
                     LOG.trace("Visiting path: {}", path);
                     try {
-                        Path baseName = isAbsolute ? sourceDir.getPath().getFileName() : sourceDir.getPath();
-                        Path relativePath = baseName.resolve(sourceDir.getPath().relativize(path));
+                        Path relativePath;
+                        if (includeDirectoryName) {
+                            Path baseName = isAbsolute ? sourceDir.getPath().getFileName() : sourceDir.getPath();
+                            relativePath = baseName.resolve(sourceDir.getPath().relativize(path));
+                        } else {
+                            relativePath = sourceDir.getPath().relativize(path);
+                        }
                         if (relativePath.toString().isEmpty()) {
                             LOG.trace("Skipping root directory: {}", path);
                             return;