Add zip compression for artifact but never unpack it (Not a standard OCI layer mediatype) (#606)

jonesbusy · web-flow · commit 31b84b19f124 · 2026-02-28T12:20:11.000+01:00
Signed-off-by: Valentin Delaye &lt;jonesbusy@users.noreply.github.com&gt;
diff --git a/src/main/java/land/oras/OCI.java b/src/main/java/land/oras/OCI.java
@@ -37,6 +37,7 @@
 import land.oras.utils.ArchiveUtils;
 import land.oras.utils.Const;
 import land.oras.utils.SupportedAlgorithm;
+import land.oras.utils.SupportedCompression;
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
@@ -163,26 +164,42 @@ protected final List<Layer> pushLayers(T ref, Annotations annotations, boolean w
             try {
                 // Create tar.gz archive for directory
                 if (Files.isDirectory(path.getPath())) {
-                    LocalPath tempTar = ArchiveUtils.tar(path);
-                    LocalPath tempArchive = ArchiveUtils.compress(tempTar, path.getMediaType());
+                    SupportedCompression compression = SupportedCompression.fromMediaType(path.getMediaType());
+
+                    // If source need to be packed first
+                    boolean autoUnpack = compression.isAutoUnpack();
+                    LocalPath tempSource = autoUnpack ? ArchiveUtils.tar(path) : path;
+                    LocalPath tempArchive = ArchiveUtils.compress(tempSource, path.getMediaType());
+
                     if (withDigest) {
                         ref = ref.withDigest(ref.getAlgorithm().digest(tempArchive.getPath()));
                     }
                     try (InputStream is = Files.newInputStream(tempArchive.getPath())) {
                         String title = path.getPath().isAbsolute()
                                 ? path.getPath().getFileName().toString()
                                 : path.getPath().toString();
+
+                        // We store the filename, based on directory name if we don't auto unpack
+                        if (!autoUnpack) {
+                            title = "%s.%s".formatted(title, compression.getFileExtension());
+                        }
                         LOG.debug("Uploading directory as archive with title: {}", title);
 
                         Map<String, String> layerAnnotations = annotations.hasFileAnnotations(title)
                                 ? annotations.getFileAnnotations(title)
                                 : new LinkedHashMap<>(Map.of(Const.ANNOTATION_TITLE, title));
 
                         // Add oras digest/unpack
-                        layerAnnotations.put(
-                                Const.ANNOTATION_ORAS_CONTENT_DIGEST,
-                                ref.getAlgorithm().digest(tempTar.getPath()));
-                        layerAnnotations.put(Const.ANNOTATION_ORAS_UNPACK, "true");
+                        // For example zip can be packed application/zip but never unpacked by the runtime
+                        // This is convenience method to pack zip layer as directories
+                        if (compression.isAutoUnpack()) {
+                            layerAnnotations.put(
+                                    Const.ANNOTATION_ORAS_CONTENT_DIGEST,
+                                    ref.getAlgorithm().digest(tempSource.getPath()));
+                            layerAnnotations.put(Const.ANNOTATION_ORAS_UNPACK, "true");
+                        } else {
+                            layerAnnotations.put(Const.ANNOTATION_ORAS_UNPACK, "false");
+                        }
 
                         Layer layer = pushBlob(ref, is)
                                 .withMediaType(path.getMediaType())
diff --git a/src/main/java/land/oras/utils/ArchiveUtils.java b/src/main/java/land/oras/utils/ArchiveUtils.java
@@ -25,6 +25,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
@@ -35,9 +36,14 @@
 import java.util.stream.Stream;
 import land.oras.LocalPath;
 import land.oras.exception.OrasException;
+import org.apache.commons.compress.archivers.ArchiveEntry;
 import org.apache.commons.compress.archivers.tar.TarArchiveEntry;
 import org.apache.commons.compress.archivers.tar.TarArchiveInputStream;
 import org.apache.commons.compress.archivers.tar.TarArchiveOutputStream;
+import org.apache.commons.compress.archivers.zip.AsiExtraField;
+import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
+import org.apache.commons.compress.archivers.zip.ZipArchiveInputStream;
+import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
 import org.apache.commons.compress.compressors.gzip.GzipCompressorInputStream;
 import org.apache.commons.compress.compressors.gzip.GzipCompressorOutputStream;
 import org.apache.commons.compress.compressors.zstandard.ZstdCompressorInputStream;
@@ -74,6 +80,18 @@ public static Path createTempTar() {
         }
     }
 
+    /**
+     * Create a temporary zip file when uploading directory layers with zip media type
+     * @return The path to the zip file
+     */
+    public static Path createTempZip() {
+        try {
+            return Files.createTempFile("oras", ".zip");
+        } catch (IOException e) {
+            throw new OrasException("Failed to create temporary zip file", e);
+        }
+    }
+
     /**
      * Create a temporary directory
      * @return The path to the temporary directory
@@ -86,6 +104,64 @@ public static Path createTempDir() {
         }
     }
 
+    /**
+     * Zip a local source dire and return a temporary zip file as a local path
+     * @param sourceDir The source directory
+     * @return The local path to the zip file
+     */
+    public static LocalPath zip(LocalPath sourceDir) {
+        Path zipFile = createTempZip();
+        boolean isAbsolute = sourceDir.getPath().isAbsolute();
+        try (OutputStream fos = Files.newOutputStream(zipFile);
+                BufferedOutputStream bos = new BufferedOutputStream(fos);
+                ZipArchiveOutputStream zaos = new ZipArchiveOutputStream(bos)) {
+            try (Stream<Path> paths = Files.walk(sourceDir.getPath())) {
+                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));
+                        if (relativePath.toString().isEmpty()) {
+                            LOG.trace("Skipping root directory: {}", path);
+                            return;
+                        }
+                        String entryName = relativePath.toString();
+                        if (Files.isSymbolicLink(path)) {
+                            LOG.trace("Adding symlink entry to zip: {}", entryName);
+                            Path linkTarget = Files.readSymbolicLink(path);
+                            ZipArchiveEntry entry = new ZipArchiveEntry(entryName);
+                            AsiExtraField asiField = new AsiExtraField();
+                            asiField.setLinkedFile(linkTarget.toString());
+                            // 0120000 = S_IFLNK (symlink file type), 0755 = permissions
+                            asiField.setMode(0120755);
+                            entry.addExtraField(asiField);
+                            entry.setSize(0);
+                            zaos.putArchiveEntry(entry);
+                        } else if (Files.isDirectory(path)) {
+                            LOG.trace("Adding directory entry to zip: {}", entryName + "/");
+                            ZipArchiveEntry entry = new ZipArchiveEntry(entryName + "/");
+                            zaos.putArchiveEntry(entry);
+                        } else {
+                            LOG.trace("Adding file entry to zip: {}", entryName);
+                            ZipArchiveEntry entry = new ZipArchiveEntry(entryName);
+                            entry.setSize(Files.size(path));
+                            zaos.putArchiveEntry(entry);
+                            try (InputStream fis = Files.newInputStream(path)) {
+                                fis.transferTo(zaos);
+                            }
+                        }
+                        zaos.closeArchiveEntry();
+                    } catch (IOException e) {
+                        throw new OrasException("Failed to create zip file", e);
+                    }
+                });
+            }
+        } catch (IOException e) {
+            throw new OrasException("Failed to create zip file", e);
+        }
+        return LocalPath.of(zipFile, Const.ZIP_MEDIA_TYPE);
+    }
+
     /**
      * Create a tar.gz file from a directory
      * @param sourceDir The source directory
@@ -177,7 +253,7 @@ public static LocalPath tarcompress(LocalPath sourceDir, String mediaType) {
      * @param target The target directory
      * @throws IOException
      */
-    static void ensureSafeEntry(TarArchiveEntry entry, Path target) throws IOException {
+    static void ensureSafeEntry(ArchiveEntry entry, Path target) throws IOException {
         // Prevent path traversal attacks
         Path outputPath = target.resolve(entry.getName()).normalize();
         Path normalizedTarget = target.toAbsolutePath().normalize();
@@ -237,6 +313,80 @@ public static Path untar(Path path) {
         return tempDir;
     }
 
+    /**
+     * Extract a zip file to a target directory
+     * @param path The zip file
+     * @param target The target directory
+     */
+    public static void unzip(Path path, Path target) {
+        try {
+            unzip(Files.newInputStream(path), target);
+        } catch (IOException e) {
+            throw new OrasException("Failed to extract zip file", e);
+        }
+    }
+
+    /**
+     * Unzip a file to a temporary directory and return the local path to the temporary directory
+     * @param fis The zip file input stream
+     * @return The local path to the temporary directory
+     */
+    static LocalPath unzip(InputStream fis) {
+        Path tempDir = createTempDir();
+        unzip(fis, tempDir);
+        return LocalPath.of(tempDir);
+    }
+
+    /**
+     * Extract a zip file to a target directory
+     * @param fis The zip file input stream
+     * @param target The target directory
+     */
+    static void unzip(InputStream fis, Path target) {
+        // Open the zip file for reading
+        try {
+            try (BufferedInputStream bis = new BufferedInputStream(fis);
+                    ZipArchiveInputStream zais = new ZipArchiveInputStream(bis)) {
+                ZipArchiveEntry entry;
+
+                // Iterate through zip entries
+                while ((entry = zais.getNextEntry()) != null) {
+
+                    // Prevent path traversal attacks
+                    Path outputPath = target.resolve(entry.getName()).normalize();
+
+                    // Check if the entry is outside the target directory
+                    ensureSafeEntry(entry, target);
+
+                    if (entry.isDirectory()) {
+                        LOG.debug("Extracting directory: {}", entry.getName());
+                        Files.createDirectories(outputPath);
+                    }
+                    // Check symlink from AsiExtraField
+                    else {
+                        AsiExtraField asiField = (AsiExtraField) entry.getExtraField(new AsiExtraField().getHeaderId());
+                        if (entry.isUnixSymlink() || (asiField != null && asiField.isLink())) {
+                            LOG.debug("Extracting symlink: {}", entry.getName());
+                            Files.createDirectories(outputPath.getParent());
+                            String linkStr = asiField != null
+                                    ? asiField.getLinkedFile()
+                                    : new String(zais.readAllBytes(), StandardCharsets.UTF_8);
+                            Files.createSymbolicLink(outputPath, Paths.get(linkStr));
+                        } else {
+                            LOG.debug("Extracting file: {}", entry.getName());
+                            Files.createDirectories(outputPath.getParent());
+                            try (OutputStream out = Files.newOutputStream(outputPath)) {
+                                zais.transferTo(out);
+                            }
+                        }
+                    }
+                }
+            }
+        } catch (IOException e) {
+            throw new OrasException("Failed to extract zip file", e);
+        }
+    }
+
     /**
      * Extract a tar file to a target directory
      * @param fis The archive stream
@@ -308,7 +458,7 @@ public static LocalPath uncompress(InputStream is, String mediaType) {
 
     static LocalPath compressZstd(LocalPath tarFile) {
         LOG.trace("Compressing tar file to zstd archive");
-        Path tarGzFile = Paths.get(tarFile.toString() + ".gz");
+        Path tarGzFile = Paths.get(tarFile + ".gz");
         try (InputStream fis = Files.newInputStream(tarFile.getPath());
                 BufferedInputStream bis = new BufferedInputStream(fis);
                 OutputStream fos = Files.newOutputStream(tarGzFile);
diff --git a/src/main/java/land/oras/utils/Const.java b/src/main/java/land/oras/utils/Const.java
@@ -133,6 +133,11 @@ private Const() {
      */
     public static final String BLOB_DIR_ZSTD_MEDIA_TYPE = "application/vnd.oci.image.layer.v1.tar+zstd";
 
+    /**
+     * Zip media type
+     */
+    public static final String ZIP_MEDIA_TYPE = "application/zip";
+
     /**
      * The default artifact media type if not specified
      */
diff --git a/src/main/java/land/oras/utils/SupportedCompression.java b/src/main/java/land/oras/utils/SupportedCompression.java
@@ -40,7 +40,7 @@ public enum SupportedCompression {
     /**
      * No compression
      */
-    NO_COMPRESSION(Const.DEFAULT_BLOB_MEDIA_TYPE, (localPath -> localPath), (is -> {
+    NO_COMPRESSION(Const.DEFAULT_BLOB_MEDIA_TYPE, "tar", (localPath -> localPath), (is -> {
         // This is just a tar we need to copy the stream to a temporary file
         try {
             Path temp = ArchiveUtils.createTempTar();
@@ -51,21 +51,31 @@ public enum SupportedCompression {
         }
     })),
 
+    /**
+     * ZIP
+     */
+    ZIP(Const.ZIP_MEDIA_TYPE, "zip", ArchiveUtils::zip, ArchiveUtils::unzip),
+
     /**
      * GZIP
      */
-    GZIP(Const.DEFAULT_BLOB_DIR_MEDIA_TYPE, ArchiveUtils::compressGzip, ArchiveUtils::uncompressGzip),
+    GZIP(Const.DEFAULT_BLOB_DIR_MEDIA_TYPE, "gz", ArchiveUtils::compressGzip, ArchiveUtils::uncompressGzip),
 
     /**
      * ZSTD
      */
-    ZSTD(Const.BLOB_DIR_ZSTD_MEDIA_TYPE, ArchiveUtils::compressZstd, ArchiveUtils::uncompressZstd);
+    ZSTD(Const.BLOB_DIR_ZSTD_MEDIA_TYPE, "zst", ArchiveUtils::compressZstd, ArchiveUtils::uncompressZstd);
 
     /**
      * The media type
      */
     private final String mediaType;
 
+    /**
+     * The file extension
+     */
+    private final String fileExtension;
+
     /**
      * The compress function
      */
@@ -82,13 +92,31 @@ public enum SupportedCompression {
      */
     SupportedCompression(
             String mediaType,
+            String fileExtension,
             Function<LocalPath, LocalPath> compressFunction,
             Function<InputStream, LocalPath> uncompressFunction) {
         this.mediaType = mediaType;
+        this.fileExtension = fileExtension;
         this.compressFunction = compressFunction;
         this.uncompressFunction = uncompressFunction;
     }
 
+    /**
+     * Get the file extension
+     * @return The file extension
+     */
+    public String getFileExtension() {
+        return fileExtension;
+    }
+
+    /**
+     * Whether the media type is auto unpacked (it's an image layer, not whatever media type the user specified)
+     * @return True if the media type is auto unpacked by OCI runtime, false otherwise
+     */
+    public boolean isAutoUnpack() {
+        return getMediaType().startsWith("application/vnd.oci.image.layer.v1.tar");
+    }
+
     /**
      * Get the media type
      * @return The media type
@@ -103,9 +131,6 @@ public String getMediaType() {
      * @return The compressed path
      */
     LocalPath compress(LocalPath path) {
-        if (!path.getMediaType().equals(Const.DEFAULT_BLOB_MEDIA_TYPE)) {
-            throw new OrasException("Can only compress tar media type. Given " + path.getMediaType());
-        }
         return compressFunction.apply(path);
     }
 
@@ -123,7 +148,7 @@ LocalPath uncompress(InputStream inputStream) {
      * @param mediaType The media type
      * @return The supported algorithm
      */
-    static SupportedCompression fromMediaType(String mediaType) {
+    public static SupportedCompression fromMediaType(String mediaType) {
         for (SupportedCompression compression : SupportedCompression.values()) {
             if (mediaType.equalsIgnoreCase(compression.getMediaType())) {
                 return compression;
diff --git a/src/test/java/land/oras/RegistryTest.java b/src/test/java/land/oras/RegistryTest.java
diff --git a/src/test/java/land/oras/utils/ArchiveUtilsTest.java b/src/test/java/land/oras/utils/ArchiveUtilsTest.java
