Add preservePermissions config and include permissions in cache checksum

When preservePermissions=true (default), Unix file permissions are stored in
ZIP entry headers, making them part of the ZIP file's binary content. This
ensures that hashing the ZIP file (for cache keys) includes permission
information, providing proper cache invalidation when file permissions change.

This addresses the architectural correctness concern raised in PR apache#392 review:
permissions should be in the checksum if they're being preserved, similar to
how Git includes file mode in tree hashes.

Changes:
- Added preservePermissions boolean parameter to CacheUtils.zip() and unzip()
- Added preservePermissions config option to build-cache-config.mdo (default: true)
- Added isPreservePermissions() method to CacheConfig interface and implementation
- Updated CacheControllerImpl to pass preservePermissions config to zip/unzip
- Made permission preservation conditional based on the config flag
- Fixed permissionsToMode() to include file type bits (0100000 for regular files)
- Added comprehensive tests:
  * testPermissionsAffectFileHashWhenEnabled() - Verifies different permissions
    produce different ZIP hashes when preservation is enabled
  * testPermissionsDoNotAffectHashWhenDisabled() - Verifies permissions are NOT
    preserved when the flag is disabled
- Added JavaDoc explaining that permissions become part of cache checksum

Behavior:
- preservePermissions=true: Permissions stored in ZIP, affect cache key (default)
- preservePermissions=false: Permissions not preserved, files use system umask

This is analogous to Git's treatment of file mode in tree hashes, ensuring
that metadata included in cache restoration is also part of cache key computation.

Optimize filesystem capability check to avoid repeated exceptions

Addresses reviewer feedback: check once if filesystem supports POSIX file
attributes instead of throwing and catching UnsupportedOperationException
for every file during zip/unzip operations.

Changes:
- Added single filesystem capability check at the beginning of zip() and unzip()
- Removed try-catch blocks from inside the file iteration loops
- Improved performance on non-POSIX filesystems (e.g., Windows)

Before: UnsupportedOperationException thrown and caught for every file
After: Single supportedFileAttributeViews() check per zip/unzip operation

This is more efficient and cleaner code while maintaining identical behavior.

Author: cowwoc

src/main/java/org/apache/maven/buildcache/CacheControllerImpl.java

@@ -881,7 +881,7 @@ private boolean zipAndAttachArtifact(MavenProject project, Path dir, String clas
             throws IOException {
         Path temp = Files.createTempFile("maven-incremental-", project.getArtifactId());
         temp.toFile().deleteOnExit();
-        boolean hasFile = CacheUtils.zip(dir, temp, glob);
+        boolean hasFile = CacheUtils.zip(dir, temp, glob, cacheConfig.isPreservePermissions());
         if (hasFile) {
             projectHelper.attachArtifact(project, "zip", classifier, temp.toFile());
         }
@@ -896,7 +896,7 @@ private void restoreGeneratedSources(Artifact artifact, Path artifactFilePath, M
         if (!Files.exists(outputDir)) {
             Files.createDirectories(outputDir);
         }
-        CacheUtils.unzip(artifactFilePath, outputDir);
+        CacheUtils.unzip(artifactFilePath, outputDir, cacheConfig.isPreservePermissions());
     }
 
     // TODO: move to config

src/main/java/org/apache/maven/buildcache/CacheUtils.java

@@ -159,11 +159,21 @@ public static boolean isArchive(File file) {
      * @param dir directory to zip
      * @param zip zip to populate
      * @param glob glob to apply to filenames
+     * @param preservePermissions whether to preserve Unix file permissions in the zip.
+     *                           <p><b>Important:</b> When {@code true}, permissions are stored in ZIP entry headers,
+     *                           which means they become part of the ZIP file's binary content. As a result, hashing
+     *                           the ZIP file (e.g., for cache keys) will include permission information, ensuring
+     *                           cache invalidation when file permissions change. This behavior is similar to how Git
+     *                           includes file mode in tree hashes.</p>
      * @return true if at least one file has been included in the zip.
      * @throws IOException
      */
-    public static boolean zip(final Path dir, final Path zip, final String glob) throws IOException {
+    public static boolean zip(final Path dir, final Path zip, final String glob, boolean preservePermissions) throws IOException {
         final MutableBoolean hasFiles = new MutableBoolean();
+        // Check once if filesystem supports POSIX permissions instead of catching exceptions for every file
+        final boolean supportsPosix = preservePermissions
+                && dir.getFileSystem().supportedFileAttributeViews().contains("posix");
+
         try (ZipArchiveOutputStream zipOutputStream = new ZipArchiveOutputStream(Files.newOutputStream(zip))) {
 
             PathMatcher matcher =
@@ -178,12 +188,10 @@ public FileVisitResult visitFile(Path path, BasicFileAttributes basicFileAttribu
                         final ZipArchiveEntry zipEntry =
                                 new ZipArchiveEntry(dir.relativize(path).toString());
 
-                        // Preserve Unix permissions if available
-                        try {
+                        // Preserve Unix permissions if requested and filesystem supports it
+                        if (supportsPosix) {
                             Set<PosixFilePermission> permissions = Files.getPosixFilePermissions(path);
                             zipEntry.setUnixMode(permissionsToMode(permissions));
-                        } catch (UnsupportedOperationException e) {
-                            // Not a POSIX filesystem, permissions not available
                         }
 
                         zipOutputStream.putArchiveEntry(zipEntry);
@@ -198,7 +206,11 @@ public FileVisitResult visitFile(Path path, BasicFileAttributes basicFileAttribu
         return hasFiles.booleanValue();
     }
 
-    public static void unzip(Path zip, Path out) throws IOException {
+    public static void unzip(Path zip, Path out, boolean preservePermissions) throws IOException {
+        // Check once if filesystem supports POSIX permissions instead of catching exceptions for every file
+        final boolean supportsPosix = preservePermissions
+                && out.getFileSystem().supportedFileAttributeViews().contains("posix");
+
         try (ZipArchiveInputStream zis = new ZipArchiveInputStream(Files.newInputStream(zip))) {
             ZipArchiveEntry entry = zis.getNextEntry();
             while (entry != null) {
@@ -215,14 +227,12 @@ public static void unzip(Path zip, Path out) throws IOException {
                 }
                 Files.setLastModifiedTime(file, FileTime.fromMillis(entry.getTime()));
 
-                // Restore Unix permissions if available
-                int unixMode = entry.getUnixMode();
-                if (unixMode != 0) {
-                    try {
+                // Restore Unix permissions if requested and filesystem supports it
+                if (supportsPosix) {
+                    int unixMode = entry.getUnixMode();
+                    if (unixMode != 0) {
                         Set<PosixFilePermission> permissions = modeToPermissions(unixMode);
                         Files.setPosixFilePermissions(file, permissions);
-                    } catch (UnsupportedOperationException e) {
-                        // Not a POSIX filesystem, cannot set permissions
                     }
                 }
 
@@ -248,10 +258,12 @@ public static <T> void debugPrintCollection(
      * Convert POSIX file permissions to Unix mode integer.
      *
      * @param permissions POSIX file permissions
-     * @return Unix mode as integer (e.g., 0755)
+     * @return Unix mode as integer (e.g., {@code 0100755} for regular file with rwxr-xr-x)
      */
     private static int permissionsToMode(Set<PosixFilePermission> permissions) {
-        int mode = 0;
+        // Start with regular file type (0100000 in octal)
+        int mode = 0100000;
+
         if (permissions.contains(PosixFilePermission.OWNER_READ)) {
             mode |= 0400;
         }
@@ -285,11 +297,12 @@ private static int permissionsToMode(Set<PosixFilePermission> permissions) {
     /**
      * Convert Unix mode integer to POSIX file permissions.
      *
-     * @param mode Unix mode (e.g., 0755)
+     * @param mode Unix mode (e.g., {@code 0100755} for regular file with rwxr-xr-x)
      * @return Set of POSIX file permissions
      */
     private static Set<PosixFilePermission> modeToPermissions(int mode) {
         Set<PosixFilePermission> permissions = new HashSet<>();
+        // Extract permission bits (lower 9 bits), ignoring file type bits
         if ((mode & 0400) != 0) {
             permissions.add(PosixFilePermission.OWNER_READ);
         }

src/main/java/org/apache/maven/buildcache/xml/CacheConfig.java

@@ -108,6 +108,8 @@ public interface CacheConfig {
 
     List<DirName> getAttachedOutputs();
 
+    boolean isPreservePermissions();
+
     boolean adjustMetaInfVersion();
 
     boolean calculateProjectVersionChecksum();

src/main/java/org/apache/maven/buildcache/xml/CacheConfigImpl.java

@@ -578,6 +578,13 @@ public List<DirName> getAttachedOutputs() {
         return attachedOutputs == null ? Collections.emptyList() : attachedOutputs.getDirNames();
     }
 
+    @Override
+    public boolean isPreservePermissions() {
+        checkInitializedState();
+        final AttachedOutputs attachedOutputs = getConfiguration().getAttachedOutputs();
+        return attachedOutputs == null || attachedOutputs.isPreservePermissions();
+    }
+
     @Override
     public boolean adjustMetaInfVersion() {
         if (isEnabled()) {

src/main/mdo/build-cache-config.mdo

@@ -376,6 +376,12 @@ under the License.
             <name>AttachedOutputs</name>
             <description>Section relative to outputs which are not artifacts but need to be saved/restored.</description>
             <fields>
+                <field>
+                    <name>preservePermissions</name>
+                    <type>boolean</type>
+                    <defaultValue>true</defaultValue>
+                    <description>Preserve Unix file permissions when saving/restoring attached outputs. When enabled, permissions are stored in ZIP entry headers and become part of the cache key, ensuring cache invalidation when permissions change. This is similar to how Git includes file mode in tree hashes. Disabling this may improve portability across different systems but will not preserve executable bits.</description>
+                </field>
                 <field>
                     <name>dirNames</name>
                     <association>

src/test/java/org/apache/maven/buildcache/CacheUtilsPermissionsTest.java

@@ -0,0 +1,164 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.buildcache;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.PosixFilePermission;
+import java.nio.file.attribute.PosixFilePermissions;
+import java.util.Arrays;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Tests for permission preservation in CacheUtils.zip() and CacheUtils.unzip() methods.
+ * These tests verify that Unix file permissions affect ZIP file hashes when preservation
+ * is enabled, and do not affect hashes when disabled.
+ */
+class CacheUtilsPermissionsTest {
+
+    @TempDir
+    Path tempDir;
+
+    /**
+     * Tests that ZIP file hash changes when permissions change (when preservePermissions=true).
+     * This ensures that the cache invalidates when file permissions change, maintaining
+     * cache correctness similar to how Git includes file mode in tree hashes.
+     */
+    @Test
+    void testPermissionsAffectFileHashWhenEnabled() throws IOException {
+        // Skip test on non-POSIX filesystems (e.g., Windows)
+        if (!tempDir.getFileSystem().supportedFileAttributeViews().contains("posix")) {
+            return;
+        }
+
+        // Given: Same directory content with different permissions
+        Path sourceDir1 = tempDir.resolve("source1");
+        Files.createDirectories(sourceDir1);
+        Path file1 = sourceDir1.resolve("script.sh");
+        writeString(file1, "#!/bin/bash\necho hello");
+
+        // Set executable permissions (755)
+        Set<PosixFilePermission> execPermissions = PosixFilePermissions.fromString("rwxr-xr-x");
+        Files.setPosixFilePermissions(file1, execPermissions);
+
+        // Create second directory with identical content but different permissions
+        Path sourceDir2 = tempDir.resolve("source2");
+        Files.createDirectories(sourceDir2);
+        Path file2 = sourceDir2.resolve("script.sh");
+        writeString(file2, "#!/bin/bash\necho hello");  // Identical content
+
+        // Set non-executable permissions (644)
+        Set<PosixFilePermission> normalPermissions = PosixFilePermissions.fromString("rw-r--r--");
+        Files.setPosixFilePermissions(file2, normalPermissions);
+
+        // When: Create ZIP files with preservePermissions=true
+        Path zip1 = tempDir.resolve("cache1.zip");
+        Path zip2 = tempDir.resolve("cache2.zip");
+        CacheUtils.zip(sourceDir1, zip1, "*", true);
+        CacheUtils.zip(sourceDir2, zip2, "*", true);
+
+        // Then: ZIP files should have different hashes despite identical content
+        byte[] hash1 = Files.readAllBytes(zip1);
+        byte[] hash2 = Files.readAllBytes(zip2);
+
+        boolean hashesAreDifferent = !Arrays.equals(hash1, hash2);
+        assertTrue(hashesAreDifferent,
+                "ZIP files with same content but different permissions should have different hashes " +
+                "when preservePermissions=true. This ensures cache invalidation when permissions change " +
+                "(executable vs non-executable files).");
+    }
+
+    /**
+     * Tests that ZIP file hash does NOT significantly vary when permissions change but
+     * preservePermissions=false. While ZIP timestamps may still cause minor differences,
+     * the key point is that permission information is NOT deterministically stored.
+     */
+    @Test
+    void testPermissionsDoNotAffectHashWhenDisabled() throws IOException {
+        // Skip test on non-POSIX filesystems (e.g., Windows)
+        if (!tempDir.getFileSystem().supportedFileAttributeViews().contains("posix")) {
+            return;
+        }
+
+        // Given: Same directory content with different permissions
+        Path sourceDir1 = tempDir.resolve("source1");
+        Files.createDirectories(sourceDir1);
+        Path file1 = sourceDir1.resolve("script.sh");
+        writeString(file1, "#!/bin/bash\necho hello");
+
+        // Set executable permissions (755)
+        Set<PosixFilePermission> execPermissions = PosixFilePermissions.fromString("rwxr-xr-x");
+        Files.setPosixFilePermissions(file1, execPermissions);
+
+        // Create second directory with identical content but different permissions
+        Path sourceDir2 = tempDir.resolve("source2");
+        Files.createDirectories(sourceDir2);
+        Path file2 = sourceDir2.resolve("script.sh");
+        writeString(file2, "#!/bin/bash\necho hello");  // Identical content
+
+        // Set non-executable permissions (644)
+        Set<PosixFilePermission> normalPermissions = PosixFilePermissions.fromString("rw-r--r--");
+        Files.setPosixFilePermissions(file2, normalPermissions);
+
+        // When: Create ZIP files with preservePermissions=false
+        Path zip1 = tempDir.resolve("cache1.zip");
+        Path zip2 = tempDir.resolve("cache2.zip");
+        CacheUtils.zip(sourceDir1, zip1, "*", false);
+        CacheUtils.zip(sourceDir2, zip2, "*", false);
+
+        // Unzip and verify permissions are NOT preserved
+        Path extractDir1 = tempDir.resolve("extracted1");
+        Path extractDir2 = tempDir.resolve("extracted2");
+        Files.createDirectories(extractDir1);
+        Files.createDirectories(extractDir2);
+        CacheUtils.unzip(zip1, extractDir1, false);
+        CacheUtils.unzip(zip2, extractDir2, false);
+
+        Path extractedFile1 = extractDir1.resolve("script.sh");
+        Path extractedFile2 = extractDir2.resolve("script.sh");
+
+        Set<PosixFilePermission> perms1 = Files.getPosixFilePermissions(extractedFile1);
+        Set<PosixFilePermission> perms2 = Files.getPosixFilePermissions(extractedFile2);
+
+        // Files should NOT retain their original different permissions
+        // Both should have default permissions determined by umask
+        assertFalse(perms1.equals(execPermissions) && perms2.equals(normalPermissions),
+                "When preservePermissions=false, original permissions should NOT be preserved. " +
+                "Files should use system default permissions (umask).");
+    }
+
+
+    /**
+     * Java 8 compatible version of Files.writeString().
+     */
+    private void writeString(Path path, String content) throws IOException {
+        try (OutputStream out = Files.newOutputStream(path)) {
+            out.write(content.getBytes(StandardCharsets.UTF_8));
+        }
+    }
+}