[GR-60022] Consider newDelegatingFileSystem API.

Author: tzezula

sdk/CHANGELOG.md

@@ -8,6 +8,8 @@ This changelog summarizes major changes between GraalVM SDK versions. The main f
 * GR-57817 Starting with JDK 24 users now need to configure native access privileges to the java executable in order to avoid warnings from being printed by the JDK.
 For usages of the module-path pass the `--enable-native-access=org.graalvm.truffle` option and for class-path usages pass the `--enable-native-access=ALL-UNNAMED` option to resolve the new warning. Note that Truffle automatically forwards the native access capability to all loaded languages and tools, therefore no further configuration is required. If the native access is denied by the user with `--illegal-native-access=deny` then loading the optimizing runtime will fail and the fallback runtime will be used. More information can be found in the integrity-by-default [JEP-472](https://openjdk.org/jeps/472).
 * GR-54300 `Context` and `Engine` is now automatically closed when no longer strongly referenced. A reachable `Value` or `PolyglotException` will keep the associated `Context` reachable. Additionally, the `Context` remains reachable when explicitly entered or if there is an active polyglot thread within it. The `Engine` remains reachable when there is a strongly reachable `Language`, `Instrument`, or `Context` instance. However, it is still recommended not to rely on garbage collection for closing. Instead, use the try-with-resources pattern for explicit context and engine management. For more information, refer to the [Automatic Close on GC documentation](https://github.com/oracle/graal/blob/master/truffle/docs/CloseOnGc.md).
+* GR-60022 Introduced the [FileSystem.newCompositeFileSystem](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#newCompositeFileSystem(org.graalvm.polyglot.io.FileSystem,org.graalvm.polyglot.io.FileSystem.Selector...)) method, which creates a composite `FileSystem` delegating operations to the specified delegate FileSystem instances based on the provided selectors.
+* GR-60022 Introduced the [FileSystem.newDenyIOFileSystem](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html#newDenyIOFileSystem()) method, which creates a `FileSystem` that denies all file operations except for path parsing.
 
 ## Version 24.1.0
 * GR-51177 Enable random offsets of runtime compiled function entry points for the UNTRUSTED polyglot sandbox policy.

sdk/src/org.graalvm.polyglot/snapshot.sigtest

@@ -122,6 +122,15 @@ meth public abstract java.lang.annotation.ElementType[] value()
 CLSS public abstract interface java.lang.constant.Constable
 meth public abstract java.util.Optional<? extends java.lang.constant.ConstantDesc> describeConstable()
 
+CLSS public abstract interface java.util.function.Predicate<%0 extends java.lang.Object>
+ anno 0 java.lang.FunctionalInterface()
+meth public abstract boolean test({java.util.function.Predicate%0})
+meth public java.util.function.Predicate<{java.util.function.Predicate%0}> and(java.util.function.Predicate<? super {java.util.function.Predicate%0}>)
+meth public java.util.function.Predicate<{java.util.function.Predicate%0}> negate()
+meth public java.util.function.Predicate<{java.util.function.Predicate%0}> or(java.util.function.Predicate<? super {java.util.function.Predicate%0}>)
+meth public static <%0 extends java.lang.Object> java.util.function.Predicate<{%%0}> isEqual(java.lang.Object)
+meth public static <%0 extends java.lang.Object> java.util.function.Predicate<{%%0}> not(java.util.function.Predicate<? super {%%0}>)
+
 CLSS public final org.graalvm.polyglot.Context
 innr public final Builder
 intf java.lang.AutoCloseable
@@ -147,7 +156,7 @@ meth public void leave()
 meth public void resetLimits()
 meth public void safepoint()
 supr java.lang.Object
-hfds ALL_HOST_CLASSES,EMPTY,NO_HOST_CLASSES,UNSET_HOST_LOOKUP,currentAPI,dispatch,engine,receiver
+hfds ALL_HOST_CLASSES,EMPTY,NO_HOST_CLASSES,UNSET_HOST_LOOKUP,creatorContext,currentAPI,dispatch,engine,parent,receiver
 
 CLSS public final org.graalvm.polyglot.Context$Builder
  outer org.graalvm.polyglot.Context
@@ -213,8 +222,8 @@ meth public static org.graalvm.polyglot.Engine$Builder newBuilder()
 meth public void close()
 meth public void close(boolean)
 supr java.lang.Object
-hfds EMPTY,ENGINES,currentAPI,dispatch,initializationException,receiver,shutdownHookInitialized
-hcls APIAccessImpl,ClassPathIsolation,EngineShutDownHook,ImplHolder,PolyglotInvalid
+hfds EMPTY,ENGINES,creatorEngine,currentAPI,dispatch,initializationException,receiver,shutdownHookInitialized
+hcls APIAccessImpl,CleanableReference,ContextReference,EngineReference,EngineShutDownHook,ImplHolder,PolyglotInvalid
 
 CLSS public final org.graalvm.polyglot.Engine$Builder
  outer org.graalvm.polyglot.Engine
@@ -336,16 +345,20 @@ supr java.lang.Enum<org.graalvm.polyglot.HostAccess$TargetMappingPrecedence>
 
 CLSS public final org.graalvm.polyglot.Instrument
 meth public <%0 extends java.lang.Object> {%%0} lookup(java.lang.Class<{%%0}>)
+meth public boolean equals(java.lang.Object)
+meth public int hashCode()
 meth public java.lang.String getId()
 meth public java.lang.String getName()
 meth public java.lang.String getVersion()
 meth public java.lang.String getWebsite()
 meth public org.graalvm.options.OptionDescriptors getOptions()
 supr java.lang.Object
-hfds dispatch,receiver
+hfds dispatch,engine,receiver
 
 CLSS public final org.graalvm.polyglot.Language
+meth public boolean equals(java.lang.Object)
 meth public boolean isInteractive()
+meth public int hashCode()
 meth public java.lang.String getDefaultMimeType()
 meth public java.lang.String getId()
 meth public java.lang.String getImplementationName()
@@ -355,7 +368,7 @@ meth public java.lang.String getWebsite()
 meth public java.util.Set<java.lang.String> getMimeTypes()
 meth public org.graalvm.options.OptionDescriptors getOptions()
 supr java.lang.Object
-hfds dispatch,receiver
+hfds dispatch,engine,receiver
 
 CLSS public final org.graalvm.polyglot.PolyglotAccess
 fld public final static org.graalvm.polyglot.PolyglotAccess ALL
@@ -403,7 +416,7 @@ meth public void printStackTrace(java.io.PrintStream)
 meth public void printStackTrace(java.io.PrintWriter)
 meth public void setStackTrace(java.lang.StackTraceElement[])
 supr java.lang.RuntimeException
-hfds dispatch,impl
+hfds anchor,dispatch,impl
 
 CLSS public final org.graalvm.polyglot.PolyglotException$StackFrame
  outer org.graalvm.polyglot.PolyglotException
@@ -654,7 +667,9 @@ meth public org.graalvm.polyglot.io.ByteSequence subSequence(int,int)
 meth public static org.graalvm.polyglot.io.ByteSequence create(byte[])
 
 CLSS public abstract interface org.graalvm.polyglot.io.FileSystem
+innr public abstract static Selector
 meth public !varargs boolean isSameFile(java.nio.file.Path,java.nio.file.Path,java.nio.file.LinkOption[]) throws java.io.IOException
+meth public !varargs static org.graalvm.polyglot.io.FileSystem newCompositeFileSystem(org.graalvm.polyglot.io.FileSystem,org.graalvm.polyglot.io.FileSystem$Selector[])
 meth public !varargs void copy(java.nio.file.Path,java.nio.file.Path,java.nio.file.CopyOption[]) throws java.io.IOException
 meth public !varargs void createSymbolicLink(java.nio.file.Path,java.nio.file.Path,java.nio.file.attribute.FileAttribute<?>[]) throws java.io.IOException
 meth public !varargs void move(java.nio.file.Path,java.nio.file.Path,java.nio.file.CopyOption[]) throws java.io.IOException
@@ -679,11 +694,22 @@ meth public static org.graalvm.polyglot.io.FileSystem allowInternalResourceAcces
 meth public static org.graalvm.polyglot.io.FileSystem allowLanguageHomeAccess(org.graalvm.polyglot.io.FileSystem)
  anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="")
 meth public static org.graalvm.polyglot.io.FileSystem newDefaultFileSystem()
+meth public static org.graalvm.polyglot.io.FileSystem newDenyIOFileSystem()
 meth public static org.graalvm.polyglot.io.FileSystem newFileSystem(java.nio.file.FileSystem)
 meth public static org.graalvm.polyglot.io.FileSystem newReadOnlyFileSystem(org.graalvm.polyglot.io.FileSystem)
 meth public void createLink(java.nio.file.Path,java.nio.file.Path) throws java.io.IOException
 meth public void setCurrentWorkingDirectory(java.nio.file.Path)
 
+CLSS public abstract static org.graalvm.polyglot.io.FileSystem$Selector
+ outer org.graalvm.polyglot.io.FileSystem
+cons protected init(org.graalvm.polyglot.io.FileSystem)
+intf java.util.function.Predicate<java.nio.file.Path>
+meth public abstract boolean test(java.nio.file.Path)
+meth public final org.graalvm.polyglot.io.FileSystem getFileSystem()
+meth public static org.graalvm.polyglot.io.FileSystem$Selector of(org.graalvm.polyglot.io.FileSystem,java.util.function.Predicate<java.nio.file.Path>)
+supr java.lang.Object
+hfds fileSystem
+
 CLSS public final org.graalvm.polyglot.io.IOAccess
 fld public final static org.graalvm.polyglot.io.IOAccess ALL
 fld public final static org.graalvm.polyglot.io.IOAccess NONE
@@ -772,7 +798,7 @@ intf java.lang.AutoCloseable
 meth public static org.graalvm.polyglot.management.ExecutionListener$Builder newBuilder()
 meth public void close()
 supr java.lang.Object
-hfds EMPTY,dispatch,receiver
+hfds EMPTY,creatorEngine,dispatch,receiver
 
 CLSS public final org.graalvm.polyglot.management.ExecutionListener$Builder
  outer org.graalvm.polyglot.management.ExecutionListener

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Engine.java

@@ -1955,6 +1955,16 @@ public FileSystem newNIOFileSystem(java.nio.file.FileSystem fileSystem) {
             throw noPolyglotImplementationFound();
         }
 
+        @Override
+        public FileSystem newCompositeFileSystem(FileSystem fallbackFileSystem, FileSystem.Selector... delegates) {
+            throw noPolyglotImplementationFound();
+        }
+
+        @Override
+        public FileSystem newDenyIOFileSystem() {
+            throw noPolyglotImplementationFound();
+        }
+
         @Override
         public ByteSequence asByteSequence(Object object) {
             throw noPolyglotImplementationFound();

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/impl/AbstractPolyglotImpl.java

@@ -1438,6 +1438,14 @@ public FileSystem newNIOFileSystem(java.nio.file.FileSystem fileSystem) {
         return getNext().newNIOFileSystem(fileSystem);
     }
 
+    public FileSystem newCompositeFileSystem(FileSystem fallbackFileSystem, FileSystem.Selector... delegates) {
+        return getNext().newCompositeFileSystem(fallbackFileSystem, delegates);
+    }
+
+    public FileSystem newDenyIOFileSystem() {
+        return getNext().newDenyIOFileSystem();
+    }
+
     public ByteSequence asByteSequence(Object object) {
         return getNext().asByteSequence(object);
     }

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/io/FileSystem.java

@@ -66,6 +66,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.function.Predicate;
 
 import org.graalvm.polyglot.Context;
 import org.graalvm.polyglot.Engine;
@@ -578,4 +579,119 @@ static FileSystem newReadOnlyFileSystem(FileSystem fileSystem) {
     static FileSystem newFileSystem(java.nio.file.FileSystem fileSystem) {
         return IOHelper.ImplHolder.IMPL.newNIOFileSystem(fileSystem);
     }
+
+    /**
+     * Creates a {@link FileSystem} that denies all file operations except for path parsing. Any
+     * attempt to perform file operations such as reading, writing, or deletion will result in a
+     * {@link SecurityException} being thrown.
+     * <p>
+     * Typically, this file system does not need to be explicitly installed to restrict access to
+     * host file systems. Instead, use {@code Context.newBuilder().allowIO(IOAccess.NONE)}. This
+     * method is intended primarily for use as a fallback file system in a
+     * {@link #newCompositeFileSystem(FileSystem, Selector...) composite file system}.
+     *
+     * @since 24.2
+     */
+    static FileSystem newDenyIOFileSystem() {
+        return IOHelper.ImplHolder.IMPL.newDenyIOFileSystem();
+    }
+
+    /**
+     * Creates a composite {@link FileSystem} that delegates operations to the provided
+     * {@code delegates}. The {@link FileSystem} of the first {@code delegate} whose
+     * {@link Selector#test(Path)} method accepts the path is used for the file system operation. If
+     * no {@code delegate} accepts the path, the {@code fallbackFileSystem} is used.
+     * <p>
+     * The {@code fallbackFileSystem} is responsible for parsing {@link Path} objects. All provided
+     * file systems must use the same {@link Path} type, {@link #getSeparator() separator}, and
+     * {@link #getPathSeparator() path separator}. If any file system does not meet this
+     * requirement, an {@link IllegalArgumentException} is thrown.
+     * <p>
+     * The composite file system maintains its own notion of the current working directory and
+     * ensures that the {@link #setCurrentWorkingDirectory(Path)} method is not invoked on any of
+     * the delegates. When a request to set the current working directory is received, the composite
+     * file system verifies that the specified path corresponds to an existing directory by
+     * consulting either the appropriate delegate or the {@code fallbackFileSystem}. If an explicit
+     * current working directory has been set, the composite file system normalizes and resolves all
+     * relative paths to absolute paths prior to delegating operations. Conversely, if no explicit
+     * current working directory is set, the composite file system directly forwards the incoming
+     * path, whether relative or absolute, to the appropriate delegate. Furthermore, when an
+     * explicit current working directory is set, the composite file system does not delegate
+     * {@code toAbsolutePath} operations, as delegates do not maintain an independent notion of the
+     * current working directory. If the current working directory is unset, {@code toAbsolutePath}
+     * operations are delegated to the {@code fallbackFileSystem}.
+     * <p>
+     * Operations that are independent of path context, including {@code getTempDirectory},
+     * {@code getSeparator}, and {@code getPathSeparator}, are handled exclusively by the
+     * {@code fallbackFileSystem}.
+     *
+     * @throws IllegalArgumentException if the file systems do not use the same {@link Path} type,
+     *             {@link #getSeparator() separator}, or {@link #getPathSeparator() path separator}
+     * @since 24.2
+     */
+    static FileSystem newCompositeFileSystem(FileSystem fallbackFileSystem, Selector... delegates) {
+        return IOHelper.ImplHolder.IMPL.newCompositeFileSystem(fallbackFileSystem, delegates);
+    }
+
+    /**
+     * A selector for determining which {@link FileSystem} should handle operations on a given
+     * {@link Path}. This class encapsulates a {@link FileSystem} and defines a condition for
+     * selecting it.
+     *
+     * @since 24.2
+     */
+    abstract class Selector implements Predicate<Path> {
+
+        private final FileSystem fileSystem;
+
+        /**
+         * Creates a {@link Selector} for the specified {@link FileSystem}.
+         *
+         * @since 24.2
+         */
+        protected Selector(FileSystem fileSystem) {
+            this.fileSystem = Objects.requireNonNull(fileSystem, "FileSystem must be non-null");
+        }
+
+        /**
+         * Returns the {@link FileSystem} associated with this selector.
+         *
+         * @since 24.2
+         */
+        public final FileSystem getFileSystem() {
+            return fileSystem;
+        }
+
+        /**
+         * Tests whether the {@link FileSystem} associated with this selector can handle operations
+         * on the specified {@link Path}.
+         *
+         * @param path the path to test, provided as a normalized absolute path. The given
+         *            {@code path} has no path components equal to {@code "."} or {@code ".."}.
+         * @return {@code true} if the associated {@link FileSystem} can handle the {@code path};
+         *         {@code false} otherwise
+         * @since 24.2
+         */
+        public abstract boolean test(Path path);
+
+        /**
+         * Creates a {@link Selector} for the specified {@link FileSystem} using the provided
+         * {@link Predicate}.
+         *
+         * @param fileSystem the {@link FileSystem} to associate with the selector
+         * @param predicate the condition to determine if the {@link FileSystem} can handle a given
+         *            path
+         * @return a new {@link Selector} that delegates path testing to the {@code predicate}
+         * @since 24.2
+         */
+        public static Selector of(FileSystem fileSystem, Predicate<Path> predicate) {
+            Objects.requireNonNull(predicate, "Predicate must be non-null");
+            return new Selector(fileSystem) {
+                @Override
+                public boolean test(Path path) {
+                    return predicate.test(path);
+                }
+            };
+        }
+    }
 }