Skip to content

Latest commit

 

History

History
1917 lines (1586 loc) · 80.1 KB

FILE.adoc

File metadata and controls

1917 lines (1586 loc) · 80.1 KB

SmallMind File

Table of Contents

The smallmind-file module is a container for alternative java.nio.file FileSystem implementations — file systems that plug into the standard JDK NIO SPI (java.nio.file.spi.FileSystemProvider) but store, route, or gate their data in ways the built-in file: provider cannot.

It is organized as two independently publishable artifacts:

  • file-ephemeral — an in-memory, heap-backed FileSystem with a transparent fall-through to a native provider for paths outside its configured roots. Can be installed as the JVM default through -Djava.nio.file.spi.DefaultFileSystemProvider=….

  • file-jailed — a chroot-style FileSystem that confines all path resolution to a subtree of an underlying native file system. The jail boundary can be fixed at construction time or resolved per-call from a thread-bound context.

Neither artifact has a runtime dependency on the other. Both depend only on smallmind-nutsnbolts; the jailed artifact additionally has an optional compile-time dependency on jakarta.xml.bind-api for the JAXB annotations on RootedFileSystemContext.

The JDK ships exactly one production-grade FileSystemProvider, the platform file: provider. Everything else — in-memory sandboxes, chroot confinements, overlay trees for tests, watched virtual directories — either has to be implemented by hand or pulled in from a heavyweight dependency such as Jimfs, Memoryfs, or a full VFS library.

The two modules in smallmind-file are the minimum useful answer to two recurring needs that do not justify either of those choices:

  1. Ephemeral, default-installable in-memory storage with native pass-through. Tests want a Files.createDirectories / Files.write / Files.readString loop that leaves no disk artefacts, runs at memory speed, and still reads real classpath resources through the ordinary file: provider. A production service that wants an overlay — for example, a scratch area under /opt/epicenter/twimble that must behave like a real directory to legacy code but never touch disk — wants the same thing, but installed JVM-wide.

  2. A hard boundary around a subtree of the real file system. Code that accepts user-controlled path inputs — uploaded file managers, sandboxed plugin hosts, multi-tenant storage services — needs a FileSystem whose absolute / is someone else’s /var/lib/service/tenant-42, with every path translation gated so ../../etc/passwd cannot escape. The JDK provides no such type; this module provides two concrete strategies for it.

Both modules exist as ordinary FileSystemProvider implementations so that they integrate through java.nio.file.Files, java.nio.file.Path, and java.nio.file.Paths without any code on the caller’s side knowing that a non-standard provider is in play.

  • Not a full VFS (no zip, no SFTP, no S3). The two provided file systems are the two the repository needs; adding more is possible but is not the purpose of the module.

  • Not a security boundary on its own. The jailed provider enforces path containment at the path translation layer; it does not sign, encrypt, or audit I/O, and it does not defend against kernel-level escapes such as symlink traversal on the underlying native file system. A caller that wants those properties must compose them over the jailed provider.

  • Not a persistence layer. The ephemeral provider is, by construction, lost on JVM exit.

If you are … Read, in this order

… a test author who wants a throwaway in-memory file system for the duration of a single test

Installation → Ephemeral quick start → Configuration.

… a service author installing ephemeral storage as the JVM default provider

Installing as the JVM default provider → Configuration → Native delegation in detail.

… a library author building a user-facing upload surface that must not escape a tenant directory

Jailed quick start → Translator strategies → Jail policy → Deriving the jail boundary per request.

… someone deciding how hard the jail boundary needs to be, and what a symbolic link inside it can do

Jail policy → Limitations and Known Issues.

… someone trying to understand why a call is throwing ProviderMismatchException, SecurityException, or FileSystemAlreadyExistsException

Error Model.

Artifact Ships Reach for it when Module name

file-ephemeral

EphemeralFileSystemProvider, EphemeralFileSystem, EphemeralFileStore, heap tree, symbolic and hard links, seekable and file channels, enforced capacity, watch service

You need a FileSystem whose storage is RAM and whose paths can either stand alone (ephemeral:///…) or masquerade as the JVM default (file:///…) with transparent pass-through for anything outside the configured roots.

org.smallmind.file.ephemeral

file-jailed

JailedFileSystemProvider, JailedFileSystem, JailedPath, JailedPathTranslator strategy tree, JailPolicy link confinement, jail-space glob matching and watch service

You need a FileSystem whose / is actually a subtree of some other native file system, and every path operation must be guarded from escaping that subtree.

org.smallmind.file.jailed

A few terms recur throughout this module.

Provider-managed singleton

Both EphemeralFileSystemProvider and JailedFileSystemProvider maintain exactly one FileSystem instance per provider. Calls to newFileSystem(URI, Map) always throw FileSystemAlreadyExistsException; getFileSystem(URI) returns the single pre-constructed instance after validating the URI. This is a deliberate choice: it keeps the mapping between scheme and provider unambiguous when the provider is registered through the SPI.

Scheme mirroring

The ephemeral provider has a no-arg constructor using the scheme "ephemeral" and a EphemeralFileSystemProvider(FileSystemProvider) constructor that mirrors the scheme of another provider (typically the platform file: provider) and captures a reference to that provider’s root file system. When the provider is installed as the JVM default and mirrors the file: scheme, ephemeral paths and native paths can coexist under the same Paths.get(…​) call, with the EphemeralFileSystemConfiguration deciding which ones are "ours".

Native delegation

In the ephemeral provider, any path the configuration does not claim is wrapped in a NativePath adapter and all operations on it are forwarded, unchanged, to the native provider. This is what makes the ephemeral provider safe to install as the JVM default: real files under C:\Users\… or /usr/… are not intercepted; only paths that match the configured overlay roots are served from the heap.

Three rules decide the question, in order. A path rooted at / is claimed when it lies at or beneath a configured root, matched on whole segments. A path that is absolute in the native namespace is never claimed, whatever the roots say — on Windows a drive-qualified or UNC path does not begin with /, so without this rule it would look relative and be swallowed by the heap. Anything genuinely relative belongs to whichever file system owns the working directory.

Path translation

In the jailed provider, every operation goes through a JailedPathTranslator.unwrapPath(Path, LinkOption…​) call that converts the jailed absolute path into a native path rooted at the jail’s configured root directory. Translation normalizes the jailed path with .. clamped at the jail root, validates every name element as a single legal name on the native file system, and verifies that the assembled native path lies beneath the root. Listing operations wrap native paths back into JailedPath instances via wrapPath(…​). Any failure to confine a path raises SecurityException.

Jail policy

Structural confinement alone can be defeated by a symbolic link that lives inside the jail and points out of it, because the native file system will follow it. JailPolicy.STRICT, the default, closes that by additionally resolving the real location of the translated path and comparing it against the real path of the jail root, so an escaping link is refused rather than followed. JailPolicy.LENIENT performs no I/O and accepts the risk. See Jail policy: structural versus real-path confinement.

Heap tree

Internal name for the in-memory data structure that backs the ephemeral file store: a tree of DirectoryNode, FileNode, and LinkNode objects, each descending from a single anonymous root. File content lives in a HeapFileContent, a list of fixed-size segments addressed by absolute position, and is exposed to clients through EphemeralSeekableByteChannel and EphemeralFileChannel.

The content object holds no cursor of its own. That is the point: a channel owns only its own position, so two channels on one file advance independently, a single channel can be opened for reading and writing, and concurrent appends resolve the end of the file and write in one atomic step instead of overwriting one another.

Space accounting

Every growth of file content is reserved against a running total through the HeapSpaceGovernor the store implements, and a write that would exceed the configured capacity fails rather than succeeding and driving the reported free space negative. Because the reservation happens while a content lock is held, the counter is lock-free and never reaches back for the tree lock.

Heap event / watch translation

Mutations to the heap tree raise HeapEvent objects whose path is the changed entry. The store fires each event on the directory that contains the changed entry, and on that directory only — a NIO watch registration covers the entries of one directory and says nothing about its descendants, so events deliberately do not climb the tree. An EphemeralHeapEventListener is installed per watched directory and forwards to the EphemeralWatchService, which computes the WatchEvent context() as watchedPath.relativize(changedPath) so that the standard NIO WatchService contract is honoured end-to-end, entirely in heap.

Both artifacts are published under org.smallmind:

<dependency>
  <groupId>org.smallmind</groupId>
  <artifactId>file-ephemeral</artifactId>
  <version>${project.version}</version>
</dependency>

<dependency>
  <groupId>org.smallmind</groupId>
  <artifactId>file-jailed</artifactId>
  <version>${project.version}</version>
</dependency>

Use whichever one you need; depending on both is allowed but unusual.

file-ephemeral

Requires smallmind-nutsnbolts (for SingleItemIterable, SnowflakeId, and UnknownSwitchCaseException). Everything else is JDK-only. File content is held in HeapFileContent rather than in nutsnbolts' ByteArrayIOBuffer, whose single shared stream position is the wrong shape for a file that several channels may hold open at once.

file-jailed

Requires smallmind-nutsnbolts (for ContextFactory / Context). The jakarta.xml.bind-api dependency is marked <optional>true</optional> — it is needed only if you intend to unmarshal RootedFileSystemContext from XML. If you construct contexts programmatically, JAXB need not be on the classpath.

The jailed artifact ships a META-INF service entry:

META-INF/services/java.nio.file.spi.FileSystemProvider
  org.smallmind.file.jailed.JailedFileSystemProvider

so simply placing file-jailed on the classpath registers the jailed: scheme with FileSystems.newFileSystem(URI, Map).

The ephemeral artifact ships one too:

META-INF/services/java.nio.file.spi.FileSystemProvider
  org.smallmind.file.ephemeral.EphemeralFileSystemProvider

so placing file-ephemeral on the classpath makes FileSystems.getFileSystem(URI.create("ephemeral:///")) resolve without the application constructing a provider itself. The service loader uses the no-arg constructor, so the registered instance carries the ephemeral: scheme and performs no native delegation.

Replacing the platform file: provider is a separate and deliberate act, requested through -Djava.nio.file.spi.DefaultFileSystemProvider=… (see Installing as the JVM default provider) — a decision an application must make on purpose, and one that constrains the configuration.

Both jars ship explicit module descriptors. On the classpath the descriptors are ignored. The repository-wide rules are in Module Path And Classpath; this section lists what is specific to these two modules.

  • Each descriptor declares its provider with provides java.nio.file.spi.FileSystemProvider with …, alongside the META-INF/services entry shown above. On a module path only the provides clause counts, and the JDK’s own use of the service brings a provider module on the module path into the module graph without your module requiring it.

  • org.smallmind.file.ephemeral requires org.smallmind.nutsnbolts and exports org.smallmind.file.ephemeral, .heap, and .watch.

  • org.smallmind.file.jailed exports org.smallmind.file.jailed and re-exports org.smallmind.nutsnbolts (requires transitive), whose ContextFactory types appear in its public signatures. JAXB is requires static jakarta.xml.bind: if you unmarshal RootedFileSystemContext from XML on a module path, require jakarta.xml.bind yourself or add it with --add-modules. The package is opened to jakarta.xml.bind for that unmarshalling.

The ephemeral provider is a complete NIO file system backed entirely by heap memory, with built-in pass-through to a native provider for paths the configuration does not claim.

  • Serves a single EphemeralFileSystem instance per provider, with one EphemeralFileStore of configurable total capacity and block size.

  • Recognises a configurable set of path prefixes (roots) and routes any path that matches one of them through the in-memory heap tree.

  • Wraps every other path in a NativePath adapter that delegates to the native provider captured at construction. From the caller’s perspective, Paths.get(…​) returns a seamless Path regardless of whether it resolves to heap or disk.

  • Implements the full SeekableByteChannel, DirectoryStream, and SecureDirectoryStream contracts against the heap, so Files.newByteChannel, Files.newDirectoryStream, and Files.walkFileTree all work.

  • Implements FileChannel for ephemeral paths, so FileChannel.open works as well as Files.newByteChannel, including the positional read / write overloads and transferTo / transferFrom.

  • Supports symbolic links and hard links: createSymbolicLink, readSymbolicLink, and createLink, with NOFOLLOW_LINKS honoured throughout and link cycles reported rather than recursed. A hard link is a second FileNode over one HeapFileContent, so both names report the same fileKey, Files.isSameFile agrees, and the content outlives the deletion of either name.

  • Enforces the configured capacity. A write past it fails with an IOException, and getUsableSpace() / getUnallocatedSpace() report what is genuinely left.

  • Resolves relative paths against a configurable working directory, so a relative path is served from the heap rather than silently reaching the real disk.

  • Implements WatchService against heap events (HeapEvent → WatchEvent.Kind translation), so Files.newWatchService() produces a working in-memory watcher with the same per-directory, non-recursive scope a platform watcher has.

  • Closes what it opened. EphemeralFileSystem.close() closes every channel, directory stream, and watch service obtained through the file system, as FileSystem.close() requires, so a caller still holding one is told it is gone rather than operating on an abandoned heap.

  • Exposes a clear() method on both EphemeralFileSystem and EphemeralFileStore that drops every node, useful for test teardown.

  • No POSIX permission model. The only FileAttribute accepted by createDirectory and newByteChannel is "posix:permissions", and even that is validated only by name — the value is not stored or enforced. Only the basic attribute view is advertised.

  • No AsynchronousFileChannel support for ephemeral paths; that method exists only to delegate to the native provider when given a NativePath.

  • No memory mapping. EphemeralFileChannel.map(…​) throws UnsupportedOperationException, because content is held as a list of segments and no MappedByteBuffer can be produced over it.

  • No file locking across processes. EphemeralFileChannel.lock(…​) returns a valid FileLock, but the heap is private to one JVM so there is nothing to arbitrate with.

  • No UserPrincipalLookupService backing store. Lookups return fresh EphemeralUserPrincipal / EphemeralGroupPrincipal instances on every call.

  • Not a security boundary. The ephemeral provider offers no access control of its own; use the jailed provider on top if path-space containment is required.

Class / interface Role

EphemeralFileSystemProvider

Entry point. Manages a single EphemeralFileSystem, routes operations to the heap or to the captured native provider depending on path type, and owns the INITIALIZATION_LATCH that waitForInitialization(long, TimeUnit) exposes.

EphemeralFileSystem

The FileSystem instance. Holds the EphemeralFileStore, the configuration, and the single root EphemeralPath. Its getPath(String, String…​) consults EphemeralFileSystemConfiguration.isOurs(…​) to choose between an EphemeralPath and a NativePath wrapper.

EphemeralFileSystemConfiguration

Immutable configuration carrier: capacity, block size, roots, and working directory. The no-arg constructor reads system properties; an explicit constructor accepts the values directly and withWorkingDirectory(String) derives a variant. isOurs(first, more) matches the assembled path against each root on whole path segments, and never claims a path that is absolute in the native namespace. checkFitToBeDefaultFileSystem() refuses a configuration that could not serve as the JVM default.

EphemeralFileStore

The heap file store. Implements every mutating and attribute-reading operation exposed by the provider (newByteChannel, createDirectory, delete, copy, move, readAttributes, setAttribute, newDirectoryStream, heap-listener registration, …). All mutating methods are synchronized. Capacity and block size are enforced here.

EphemeralPath

The heap-resident Path. Stores its component names in a String[] plus an absolute flag. Provides the full Path contract including normalize, resolve, relativize, startsWith, endsWith, getFileName, getParent, and toUri.

NativePath

Adapter Path that reports the EphemeralFileSystem as its file system but delegates every structural operation to an underlying native path. The provider tests path instanceof NativePath and forwards such paths to the native provider’s implementation.

EphemeralBasicFileAttributes / EphemeralBasicFileAttributeView

BasicFileAttributes implementation. Tracks three mutable timestamps (creationTime, lastModifiedTime, lastAccessTime) and a Snowflake-generated fileKey. Per-node view instances are vended by EphemeralFileStore.getFileAttributeView(…​).

EphemeralFileStoreAttributeView

Typed attribute view for the file store. Attribute values are read by reflection against declared fields (see EphemeralFileStore.getAttribute(String)).

EphemeralDirectoryStream

SecureDirectoryStream<Path> returned by EphemeralFileStore.newDirectoryStream(…​). Relative paths passed to its secure-stream methods resolve against the stream’s own path; operations after close() throw ClosedDirectoryStreamException.

EphemeralSeekableByteChannel

Channel over the HeapFileContent of a FileNode, holding only its own position. Supports read, write, and read-and-write together. Honours DELETE_ON_CLOSE by removing the file from the store upon close(), at most once and without complaint if the file is already gone.

EphemeralFileChannel

FileChannel over the same content, for callers that reach for FileChannel.open rather than Files.newByteChannel. Adds the positional read / write overloads, transferTo / transferFrom, and force (a no-op). map(…​) throws UnsupportedOperationException.

EphemeralUserPrincipal / EphemeralGroupPrincipal / EphemeralUserPrincipalLookupService

Trivial UserPrincipal / GroupPrincipal implementations. No external backing store; lookups manufacture fresh instances.

EphemeralGlob / RegexPathMatcher

Glob-to-regex translator and the compiled-regex-backed PathMatcher. Drives EphemeralFileSystem.getPathMatcher(syntaxAndPattern) for the "glob:" and "regex:" syntaxes.

EphemeralURIUtility

URI validation (checkUri) and URI-to-path conversion (fromUri) helpers shared by the provider.

The heap subpackage, org.smallmind.file.ephemeral.heap, owns the internal data structures:

Class Role

HeapNode

Abstract base for tree nodes. Holds the parent reference, the node name, the EphemeralBasicFileAttributes, and a lazy listener list. Parent and name are mutable, so relink(DirectoryNode, String) can move a node in place — which is what lets a directory move carry its whole subtree at no cost. fire(HeapEvent) notifies the listeners on this node and no others.

DirectoryNode

Map of child names to child nodes. size() is nominal — one block — as a real file system reports the size of the directory entry rather than of its contents. All child-mutating methods are synchronized on this node.

FileNode

Leaf node referring to a HeapFileContent. Two file nodes may share one content instance, which is how a hard link is represented.

LinkNode

Leaf node holding the raw, unresolved target of a symbolic link. The target may be relative, and may not exist — a dangling link is legal, so resolution happens at lookup time.

HeapFileContent

Segmented byte storage addressed by absolute position, with no cursor of its own. Grows on demand, zero-fills a gap left by a write past the end, zeroes a truncated tail so later growth cannot expose stale bytes, and counts the names referring to it so a hard-linked file survives the deletion of one of them.

HeapSpaceGovernor

The accounting contract HeapFileContent calls before it grows and after it shrinks. EphemeralFileStore implements it, which is what turns the configured capacity into an enforced one.

HeapNodeType

Enum with three constants, FILE, DIRECTORY, and SYMBOLIC_LINK.

HeapEvent

EventObject carrying an EphemeralPath and a HeapEventType.

HeapEventListener

Callback interface invoked during HeapNode.fire(…​).

HeapEventType

Enum whose three constants (CREATE, DELETE, MODIFY) each wrap the matching StandardWatchEventKinds.ENTRY_* constant. The watch-service layer reads .getKind() on this enum to produce a standard WatchEvent.Kind.

The watch subpackage, org.smallmind.file.ephemeral.watch, ties the heap events back to NIO’s WatchService:

Class Role

EphemeralWatchService

WatchService implementation. Keeps a path → EphemeralWatchKey map and a LinkedBlockingQueue of signalled keys. Registering a path installs an EphemeralHeapEventListener on that directory node; registering it again returns the key it already has with its event kinds replaced, as Watchable.register specifies. fire(watchedPath, kind, changedPath) relativizes the changed path against the watched path to produce the WatchEvent context, and treats an event about the watched directory itself as its deletion, cancelling the key. close() enqueues a sentinel so a thread blocked in take() wakes at once rather than waiting out a polling interval.

EphemeralWatchKey

WatchKey implementation with a bounded LinkedBlockingQueue<WatchEvent<?>> of pending events (512). Once it is full a single OVERFLOW event replaces what could not be kept, so a consumer that has fallen behind is told it has rather than growing the queue without limit. Tracks valid and signalled flags; reset() re-queues the key with the service if new events arrived while it was being processed.

EphemeralWatchEvent

WatchEvent<?> record: kind, count, context.

EphemeralHeapEventListener

Bridge from HeapEvent to EphemeralWatchService.fire(…​). Each instance is created with the path it was registered on; on every event it forwards its own watched path, the heap event’s type translated to a WatchEvent.Kind, and the heap event’s changed path so the service can produce the relative context.

EphemeralFileSystemConfiguration is immutable, and has two constructors plus one derivation:

// reads system properties; falls back to defaults
public EphemeralFileSystemConfiguration ();

// explicit; the working directory becomes the first root
public EphemeralFileSystemConfiguration (long capacity,
                                         int blockSize,
                                         String... roots);

// a copy with a different working directory
public EphemeralFileSystemConfiguration withWorkingDirectory (String workingDirectory);
Note

The working directory is set through withWorkingDirectory rather than through a fourth constructor parameter on purpose. A (long, int, String, String…​) overload would compete with the varargs constructor during overload resolution, and a four-argument call such as new EphemeralFileSystemConfiguration(2048L, 512, "/opt", "/var") would bind to it — silently reinterpreting the first root as the working directory.

The four knobs are:

Knob Default Notes

capacity

Long.MAX_VALUE

An enforced ceiling on the bytes of file content the store will hold. getTotalSpace() reports it; getUsableSpace() and getUnallocatedSpace() report it less the bytes currently allocated, and never go negative. A write that would exceed it fails with an IOException naming the store and what remains. Directories and links are not charged against it.

blockSize

1024

The size of each segment HeapFileContent allocates as a file grows, and the nominal size a directory entry reports.

roots

{"/"}

The set of subtrees served from the heap. A root must start with "/", and is matched on whole path segments, so /overlay claims /overlay and /overlay/a but not /overlayed. Anything not claimed falls through to the captured native provider.

workingDirectory

the first root

The absolute directory relative paths resolve against, the ephemeral counterpart of user.dir. A relative path is served from the heap when this directory is claimed by a root, and delegated otherwise. It is created in the heap at construction, together with java.io.tmpdir when a root claims that too, so that relative I/O and Files.createTempFile work against a fresh file system instead of failing on a missing directory.

The no-arg constructor reads:

org.smallmind.file.ephemeral.configuration.capacity         = <long>
org.smallmind.file.ephemeral.configuration.blockSize        = <int>
org.smallmind.file.ephemeral.configuration.roots            = <comma-separated
                                                                list, optionally
                                                                bracketed>
org.smallmind.file.ephemeral.configuration.workingDirectory = <absolute path>

For roots, both "/opt/tmp,/var/scratch" and "[/opt/tmp, /var/scratch]" are accepted; entries that do not start with "/" are prefixed with one automatically.

To replace the platform file: provider:

-Djava.nio.file.spi.DefaultFileSystemProvider=org.smallmind.file.ephemeral.EphemeralFileSystemProvider
-Dorg.smallmind.file.ephemeral.configuration.roots=/opt/overlay,/var/scratch

# plus any of:
-Dorg.smallmind.file.ephemeral.configuration.capacity=1073741824
-Dorg.smallmind.file.ephemeral.configuration.blockSize=4096
-Dorg.smallmind.file.ephemeral.configuration.workingDirectory=/opt/overlay
Important

An explicit roots setting is required here, and the default of "/" is refused:

java.lang.IllegalArgumentException: A root of / claims every path, so it
cannot serve as the default file system, which must leave the platform
able to read its own configuration. Set
org.smallmind.file.ephemeral.configuration.roots to an overlay root,
such as /overlay.

The reason is that the platform reads its own configuration through java.nio.file.Files while it is starting up — java.security above all, by way of SecureRandom — and an empty heap has nothing to give it. Left to happen, the result is an InternalError: Error loading java.security file thrown from deep inside the security provider machinery, which says nothing about the cause. A configuration that claims java.home is refused for the same reason, and with the same rule on every platform.

The check runs only when this class is actually named in java.nio.file.spi.DefaultFileSystemProvider. Constructing new EphemeralFileSystemProvider(FileSystems.getDefault().provider()) by hand mirrors the file: scheme without answering for every path in the JVM, so it stays available for tests whatever the roots are.

When the JVM bootstraps the default file system through this property, it calls the EphemeralFileSystemProvider(FileSystemProvider) constructor, passing the platform file: provider. The resulting provider:

  • reports getScheme() == "file",

  • answers isDefault() == true,

  • captures the platform provider’s root file system in its nativeFileSystem field, and

  • routes every non-matching path through that captured file system.

From the application’s perspective, Paths.get("/opt/overlay/foo") is an EphemeralPath while Paths.get("/etc/hosts") is a NativePath wrapping the platform provider’s path — both returned by the same FileSystems.getDefault().getPath(…​) call.

The same holds on Windows, where a native absolute path carries a drive or UNC prefix instead of a leading separator: Paths.get("C:\\Program Files\\…") is a NativePath, while Paths.get("/opt/overlay/foo") is an EphemeralPath. The heap namespace is rooted at / on both platforms, which means test code addresses it identically everywhere; the corollary is that an ephemeral path is not a valid native path string on Windows, so new java.io.File(ephemeralPath.toString()) will not find it — java.io.File bypasses NIO altogether.

Note

EphemeralFileSystemProvider.waitForInitialization(long, TimeUnit) is available because, in a default-provider scenario, multiple threads may call Paths.get(…​) before the provider’s constructor has finished. The constructor counts down an internal latch after building the EphemeralFileSystem; waitForInitialization blocks on that latch.

The test in the source tree shows the smallest realistic loop:

import java.nio.ByteBuffer;
import java.nio.channels.SeekableByteChannel;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;
import java.util.Set;
import java.util.concurrent.TimeUnit;
import org.smallmind.file.ephemeral.EphemeralFileSystem;
import org.smallmind.file.ephemeral.EphemeralFileSystemProvider;

public class Demo {

  public static void main (String[] args)
    throws Exception {

    EphemeralFileSystemProvider.waitForInitialization(30, TimeUnit.SECONDS);  (1)

    Path real = Paths.get("C:\\Users\\david\\Documents\\response.txt");      (2)
    System.out.println(Files.isRegularFile(real));
    System.out.println(Files.readString(real, StandardCharsets.UTF_8));

    Path eph = Paths.get("/opt/epicenter/twimble/farkle");                    (3)
    Files.createDirectories(eph);
    try (SeekableByteChannel bc = Files.newByteChannel(
           eph.resolve("sparkle.txt"),
           Set.of(StandardOpenOption.WRITE, StandardOpenOption.CREATE))) {
      ByteBuffer bb = ByteBuffer.allocate(1024);
      bb.put("Hello out there!".getBytes(StandardCharsets.UTF_8));
      bb.flip();
      bc.write(bb);
    }
    System.out.println(new String(Files.readAllBytes(eph.resolve("sparkle.txt"))));

    ((EphemeralFileSystem)FileSystems.getDefault()).clear();                   (4)
  }
}
  1. Blocks until the default-provider constructor has built the heap file system. Safe to call even when you are not using the default-provider install; it simply returns immediately.

  2. A path that does not match any configured root. Wrapped in a NativePath and forwarded to the real platform provider.

  3. A path under a configured root (or under "/" by default). Served entirely from heap. Notice that from `Files’ point of view the two paths are indistinguishable.

  4. Drops every node. Useful at the end of a test, or between test methods, to reset the store to an empty state.

The ephemeral provider is perfectly usable as a secondary file system. Construct one directly and obtain paths through its getPath(…​):

import java.net.URI;
import java.nio.file.FileSystem;
import java.nio.file.Files;
import java.nio.file.Path;
import org.smallmind.file.ephemeral.EphemeralFileSystemProvider;

EphemeralFileSystemProvider provider = new EphemeralFileSystemProvider("overlay");
FileSystem fs = provider.getFileSystem(URI.create("overlay:///"));

Path p = fs.getPath("/scratch/demo.txt");
Files.createDirectories(p.getParent());
Files.writeString(p, "hello");

The scheme ("overlay" here) is decoupled from "file", so nothing touches the default provider and the two can coexist in the same JVM.

Note that when constructed via the no-arg or String-scheme constructor the provider has no native file system captured, so any path that does not match a configured root will cause a NullPointerException the moment the provider tries to delegate. Mix-mode usage requires the EphemeralFileSystemProvider(FileSystemProvider) form.

The watch service is a full NIO WatchService:

import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.WatchEvent;
import java.nio.file.WatchKey;
import java.nio.file.WatchService;

import static java.nio.file.StandardWatchEventKinds.ENTRY_CREATE;
import static java.nio.file.StandardWatchEventKinds.ENTRY_DELETE;
import static java.nio.file.StandardWatchEventKinds.ENTRY_MODIFY;

public void watch (Path root)
  throws Exception {

  Files.createDirectories(root);

  try (WatchService watcher = root.getFileSystem().newWatchService()) {

    root.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);   (1)

    // ... in another thread ...
    Files.writeString(root.resolve("new.txt"), "hello");                (2)

    WatchKey key = watcher.take();                                       (3)
    for (WatchEvent<?> event : key.pollEvents()) {
      System.out.println(event.kind() + " " + event.count());
    }
    key.reset();                                                         (4)
  }
}
  1. Registration creates a fresh EphemeralHeapEventListener bound to the watched path and attaches it to the directory’s DirectoryNode. The first registration per path attaches the listener; the last cancel detaches it.

  2. Any mutation to an entry of the watched directory fires the listener, which forwards the event to the service together with the changed path. A change deeper in the tree does not, exactly as with a platform watch service. The service translates the event type to a WatchEvent.Kind (ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY) and dispatches to the registered keys with watchedPath.relativize(changedPath) as the context.

  3. take() blocks on the service’s ready queue. A mid-wait close() enqueues a sentinel, so the waiting thread raises ClosedWatchServiceException at once rather than hanging.

  4. Forget to call reset() and the key will never be signalled again. If events arrived while the key was being processed, reset() requeues it immediately so it is returned by the next take().

Whenever a Path reaches any provider method, the provider performs three checks in this order:

  1. The path’s file system must be an EphemeralFileSystem. If not, a ProviderMismatchException is thrown with an explanatory message. This is the common failure mode when a caller mixes paths obtained from different providers.

  2. If the path is a NativePath, the operation is forwarded verbatim to the native provider’s implementation of the same operation, using the wrapped native path. Return values (including directory stream iterators and attribute views) come back from the native provider unchanged; they are not re-wrapped as ephemeral types.

  3. Otherwise the path is treated as an EphemeralPath, normalised, and passed to the EphemeralFileStore for the actual operation.

For two-argument operations (copy, move, isSameFile) both paths must be associated with an EphemeralFileSystem; otherwise ProviderMismatchException is raised. Cross-provider copies (ephemeral → native and vice versa) must be performed through Files.copy(InputStream, Path) / Files.copy(Path, OutputStream) rather than Files.copy(Path, Path).

The NativePath adapter is the seam that makes default-provider installation feel transparent. NativePath.getFileSystem() reports the ephemeral file system so that NIO type checks pass, but every structural operation (getRoot, resolve, normalize, toUri, compareTo, startsWith, endsWith, etc.) delegates to the wrapped native path.

The jailed provider takes an existing native file system and serves it to callers as if its root were some other configured directory on that file system. Absolute paths under the jail look like "/foo/bar"; the provider translates them to <configured-root>/foo/bar on the native side before delegating.

  • Serves a single JailedFileSystem instance per provider under the jailed: URI scheme by default (or any scheme supplied explicitly).

  • Translates every path supplied to any provider method into a native path via a JailedPathTranslator, and forwards the operation to the native provider.

  • For listing operations, wraps returned native paths back into JailedPath instances via translator.wrapPath(…​), which throws SecurityException if the native path escapes the jail.

  • Exposes two translator strategies out of the box: RootedPathTranslator (fixed native root) and ContextSensitiveRootedPathTranslator (native root read from a thread-bound RootedFileSystemContext).

  • Clamps .. at the jail root during normalization, so no amount of parent traversal walks out of the jail, and resolves a relative jailed path against the jail root.

  • Validates every name element as a single legal name on the native file system. A NUL character is always refused; when the native file system is backslash-separated, so are embedded separators, drive qualifiers, trailing dots or spaces, and the reserved device names (CON, PRN, AUX, NUL, CONIN$, CONOUT$, and COM0–COM9 / LPT0–LPT9).

  • Refuses to follow a symbolic link out of the jail under JailPolicy.STRICT, the default. See Jail policy: structural versus real-path confinement.

  • Confines watch registrations. JailedFileSystem.newWatchService() returns a JailedWatchService whose keys and events are expressed in jail space, and JailedPath.register(…​) works.

  • Matches globs in jail space. getPathMatcher("glob:…") and ("regex:…") return a JailedPathMatcher that treats / as the separator regardless of the native platform.

  • Creates a symbolic link with its target expressed relative to the link’s own directory, which keeps the jail’s real location out of the link and makes the link resolve to the confined target.

  • No defence against a link substituted between the check and the operation it guards. JailPolicy.STRICT verifies before it forwards, so a link swapped in during that window would not be caught — a race inherent to confining by path rather than by file descriptor, and one only the operating system can close. What the policy does guarantee is that a link already in place is not followed out of the jail.

  • No in-jail file store abstraction. FileStore queries delegate to the native provider.

  • No jail-level quota, audit, or interception hooks. The translator answers a single question — "is this path inside the jail?" — and everything else is native behaviour.

Class / interface Role

JailedFileSystemProvider

Entry point. Manages a single JailedFileSystem instance and a JailedPathTranslator. Every operation translates its path arguments with the translator and forwards to the native provider.

JailedFileSystem

FileSystem implementation. Delegates lifecycle and attribute views to the translator’s native file system, but answers getPathMatcher itself through JailedGlob / JailedPathMatcher and newWatchService with a JailedWatchService, so both work in jail space. Its getPath(String, String…​) returns a JailedPath.

JailedPath

Custom Path implementation. Stores the raw text as char[] and parses Segment boundaries once at construction to make navigation allocation-free. Compatible only with other JailedPath instances — cross-path operations with a foreign Path throw ProviderMismatchException. register(…​) requires a JailedWatchService.

JailedPathTranslator

Strategy interface: getNativeFileSystem, getJailPolicy, wrapPath, and unwrapPath(Path, LinkOption…​). Both translation directions may perform I/O and so declare IOException.

JailPolicy

Enum choosing how rigorously the boundary is enforced: STRICT (the default) also verifies the real, link-resolved location of a path; LENIENT applies structural confinement only and performs no I/O. See Jail policy: structural versus real-path confinement.

AbstractJailedPathTranslator

Base class providing reusable wrapPath(rootPath, …​) and unwrapPath(rootPath, …​) helpers. Normalizes with .. clamped at the root, validates each name element through asNativeName(String), verifies containment, and — under STRICT — confines the real path as well, caching the resolved jail root per root path.

JailedGlob / JailedPathMatcher

Glob-to-regex translator and the compiled-regex-backed PathMatcher behind JailedFileSystem.getPathMatcher(…​). The jail separator is always /, so a pattern means the same thing whatever the native platform.

JailedWatchService / JailedWatchKey / JailedWatchEvent

Watch-service adapters over the native watch service. A registration translates and confines its path exactly as any other operation does, and the key, its watchable(), and every event context come back expressed in jail space.

RootedPathTranslator

Fixed-root translator. The native root is passed at construction and never changes.

ContextSensitiveRootedPathTranslator

Per-call-root translator. Reads a RootedFileSystemContext from ContextFactory.getContext(…​) on every wrapPath / unwrapPath call.

RootedFileSystemContext

JAXB-annotated Context carrying the native root string. Installed into the ambient ContextFactory stack before operations run.

JailedURIUtility

Static URI validation and conversion helpers, mirroring EphemeralURIUtility.

The translator interface is the policy boundary for the jail. The module ships two implementations:

Both implementations take an optional JailPolicy; omitting it selects JailPolicy.STRICT.

A single native root decided at construction time. Appropriate when the jail boundary is known when the translator is created and never needs to change. The root must be non-null, absolute, and owned by the native file system, and is normalized on the way in:

import java.nio.file.FileSystems;
import java.nio.file.Path;
import org.smallmind.file.jailed.JailedFileSystemProvider;
import org.smallmind.file.jailed.RootedPathTranslator;

Path nativeRoot = FileSystems.getDefault().getPath("/var/lib/tenant-42");

JailedFileSystemProvider provider =
  new JailedFileSystemProvider("jailed", new RootedPathTranslator(nativeRoot));

A JailedPath.resolve("/etc/passwd") through this provider will translate to /var/lib/tenant-42/etc/passwd on the native side — which either resolves to a file that tenant has deliberately placed there or to NoSuchFileException. What it never resolves to is the real /etc/passwd, because RootedPathTranslator.unwrapPath(jailedPath) appends segments to nativeRoot rather than treating them as absolute.

To trade the link check for speed, name the policy explicitly:

new RootedPathTranslator(nativeRoot, JailPolicy.LENIENT)

Both policies apply the same structural confinement — .. clamped at the root, each name element validated, and the assembled native path verified to lie beneath the root. They differ in whether the real location of that path is checked as well.

Policy Behaviour

STRICT

The default. The deepest existing ancestor of the translated path is resolved with toRealPath(…​) and compared against the real path of the jail root, so a symbolic link inside the jail that points out of it is refused rather than followed. Resolving both sides also means a jail root that is itself reached through a link — a /tmp that links to /private/tmp, a Windows short-name alias — is still recognized as the jail root. Costs one or two extra lookups per translated path.

LENIENT

Structural confinement only, and no I/O at all. Cheaper, but a link (or a Windows junction or other reparse point) that lives inside the jail and points outside of it will be followed out by the native file system. Choose it only when the contents of the jail are trusted, or when the native file system has no notion of links.

Under STRICT, passing LinkOption.NOFOLLOW_LINKS excludes the final name element from the check, so an escaping link may still be deleted or have its own attributes read — only reading through it is refused.

The native root is read on every call from a thread-bound RootedFileSystemContext. Appropriate when the same provider must serve different tenants, sessions, or request scopes in the same JVM:

import java.nio.file.FileSystems;
import org.smallmind.file.jailed.ContextSensitiveRootedPathTranslator;
import org.smallmind.file.jailed.JailedFileSystemProvider;
import org.smallmind.file.jailed.RootedFileSystemContext;
import org.smallmind.nutsnbolts.context.ContextFactory;

JailedFileSystemProvider provider =
  new JailedFileSystemProvider(
    "jailed",
    new ContextSensitiveRootedPathTranslator(FileSystems.getDefault()));

// later, at request time:
RootedFileSystemContext ctx = new RootedFileSystemContext();
ctx.setRoot("/var/lib/tenant-42");
ContextFactory.pushContext(ctx);                          (1)

try {
  // all jailed-path operations on this thread now translate against
  // /var/lib/tenant-42
} finally {
  ContextFactory.popContext(RootedFileSystemContext.class);  (2)
}
  1. The push/pop API here is the smallmind-nutsnbolts ContextFactory contract; consult that module for the exact method names and thread-binding semantics.

  2. If the context is missing or its getRoot() is null when a jailed-file-system operation runs, ContextSensitiveRootedPathTranslator throws SecurityException with the message "No authorization for path". The jail fails closed.

The context-sensitive translator is the recommended pattern for services that handle multiple tenants, users, or request scopes through one JailedFileSystemProvider. The typical shape is:

  1. A request-scoped interceptor (servlet filter, Jersey filter, RPC request handler, …) resolves the authorised native root for the current caller.

  2. The interceptor pushes a RootedFileSystemContext with that root onto the ContextFactory stack.

  3. Business logic performs Files.* operations on JailedPath instances. Each call hits unwrapPath(…​), which consults the context, and produces an absolute native path anchored at the request’s root.

  4. The interceptor pops the context on request completion. Any subsequent operation without a context fails closed with SecurityException.

Because the context is consulted per call, the caller never has to manage a file-system instance per tenant; the single provider serves all of them.

The no-arg JailedFileSystemProvider() is what the SPI instantiates when the artifact is on the classpath. It calls:

this("jailed", new ContextSensitiveRootedPathTranslator(FileSystems.getDefault()));

That means just dropping file-jailed on the classpath registers a jailed: provider whose root must be supplied at call time via a RootedFileSystemContext. Without a context in scope, every call fails with SecurityException.

A service that wants different defaults — a fixed root, a different scheme, a non-default native file system — must construct and register its own JailedFileSystemProvider explicitly. The SPI-installed default is intentionally useless without a context: fail-closed is the safer initial state.

Using RootedPathTranslator with a fixed root:

import java.net.URI;
import java.nio.file.FileSystem;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.Path;
import org.smallmind.file.jailed.JailedFileSystemProvider;
import org.smallmind.file.jailed.RootedPathTranslator;

public class JailedDemo {

  public static void main (String[] args)
    throws Exception {

    Path root = FileSystems.getDefault().getPath("/var/lib/tenant-42");        (1)
    Files.createDirectories(root);

    JailedFileSystemProvider provider =
      new JailedFileSystemProvider("jailed", new RootedPathTranslator(root));  (2)
    FileSystem fs = provider.getFileSystem(URI.create("jailed:///"));          (3)

    Path inside = fs.getPath("/reports/2026/q2.csv");                          (4)
    Files.createDirectories(inside.getParent());
    Files.writeString(inside, "col1,col2\n1,2\n");

    Path escapeAttempt = fs.getPath("/../../etc/passwd");                      (5)
    try {
      Files.readAllBytes(escapeAttempt);
    } catch (SecurityException ignored) {
      // expected: translator rejects the attempt on wrap/unwrap
    }
  }
}
  1. The native root. Whatever this directory contains is what the jail exposes under /.

  2. Construct the provider with a fixed-root translator.

  3. The URI here must be "jailed:///" — scheme matches, authority is absent, path is exactly "/", no query, no fragment (see JailedURIUtility.checkUri).

  4. Creating a directory and writing a file inside the jail — the Files.* calls see a straightforward absolute path; the translator converts it to /var/lib/tenant-42/reports/2026/q2.csv on the way into the native provider.

  5. Attempting to escape. .. segments are not expanded by the translator itself; normalisation happens on the native side, and if the native path falls outside the root, wrapPath’s `startsWith check rejects it when the result of a listing iterator needs to be re-wrapped. In practice the escape surface is the set of places where wrapPath runs — primarily directory listings and any caller that passes a native path back through.

Note

The translator’s unwrapPath is effectively a resolve operation: it treats the jailed path as relative to the native root and appends its segments. A ".." segment in the jailed path will travel into the native path as a literal .., and the native provider will evaluate it. If the native provider normalises the resulting path out of the jail — for example, because /var/lib/tenant-42/../../etc/passwd resolves to /etc/passwd — you lose containment. Either pre-normalise on the caller side (path.normalize() on the jailed path rejects .. escapes by wrapping), or require symlink-free roots whose parent chains are trusted.

import java.net.URI;
import java.nio.file.FileSystem;
import java.nio.file.Files;
import org.smallmind.file.ephemeral.EphemeralFileSystem;
import org.smallmind.file.ephemeral.EphemeralFileSystemProvider;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeClass;

public class FooTest {

  private EphemeralFileSystemProvider provider;
  private FileSystem fs;

  @BeforeClass
  public void setup () {

    provider = new EphemeralFileSystemProvider("test");
    fs = provider.getFileSystem(URI.create("test:///"));
  }

  @AfterMethod
  public void resetHeap () {

    ((EphemeralFileSystem)fs).clear();
  }

  // tests use fs.getPath(...) freely; each test starts with an empty heap.
}

Mount an in-memory scratch area at /opt/scratch while leaving everything else on real disk. Start the JVM with:

-Djava.nio.file.spi.DefaultFileSystemProvider=org.smallmind.file.ephemeral.EphemeralFileSystemProvider
-Dorg.smallmind.file.ephemeral.configuration.roots=/opt/scratch
-Dorg.smallmind.file.ephemeral.configuration.capacity=2147483648

Paths.get("/opt/scratch/session-123/state.bin") is now an ephemeral path, served from heap, with all NIO operations including watch available. Paths.get("/etc/hosts") still reads the real file.

Request handler pseudocode, using the context-sensitive translator installed by the SPI default:

import java.net.URI;
import java.nio.file.FileSystem;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.Path;
import org.smallmind.file.jailed.RootedFileSystemContext;
import org.smallmind.nutsnbolts.context.ContextFactory;

public void handleUpload (String tenantId, String relativePath, byte[] bytes)
  throws IOException {

  RootedFileSystemContext ctx = new RootedFileSystemContext();
  ctx.setRoot("/var/lib/tenants/" + tenantId);
  ContextFactory.pushContext(ctx);

  try {
    FileSystem fs = FileSystems.getFileSystem(URI.create("jailed:///"));
    Path target = fs.getPath("/").resolve(relativePath).normalize();   (1)

    Files.createDirectories(target.getParent());
    Files.write(target, bytes);
  } finally {
    ContextFactory.popContext(RootedFileSystemContext.class);
  }
}
  1. Normalise inside the jail so that .. sequences collapse within the JailedPath before the translator sees them. Combined with a symlink-free tenant root, this is the minimum precaution against path-traversal escapes.

EphemeralFileSystem.getPath(first, more) decides between EphemeralPath and NativePath in three steps:

  1. A /-rooted path is claimed when it equals a configured root or lies beneath one on a segment boundary, so /overlay claims /overlay and /overlay/a but not /overlayed.

  2. A path that is absolute in the native namespace is never claimed, whatever the roots say.

  3. Anything genuinely relative is claimed when the working directory is claimed.

Warning

Rule 2 is not a nicety. A Windows path such as C:\Users\… does not begin with /, so without it the path falls through to rule 3, is taken for a relative path, and is claimed whenever the working directory is — handing every real file on the machine to an empty heap. Installed as the JVM default that leaves the platform unable to read java.security, and start-up dies with InternalError.

The rule is applied in two places, deliberately. EphemeralFileSystem.getPath(…​) puts the question of what makes a path absolute to the native file system itself, so no platform’s spelling of a root has to be recognized in this code. EphemeralFileSystemConfiguration.isOurs(…​) also applies a syntactic test for a drive qualifier or a UNC prefix, performing no I/O, so that a caller asking the configuration directly gets the same answer — and so that the test is safe to run while FileSystems is still resolving its default provider.

EphemeralOverlayRoutingTest pins this matrix using literal Linux-shaped and Windows-shaped path strings, so the whole decision is exercised on either platform.

EphemeralFileSystem.close() is a no-op when the file system is installed as the default provider (isDefault() == true) — the default file system cannot be closed. Otherwise it closes every channel, directory stream, and watch service opened through the file system, and then marks the file system closed.

Each resource is tracked from the moment it is handed out until it closes itself, so a caller who uses try-with-resources costs nothing here. The ordering matters, and it favours the stronger guarantee: the closed flag is set before any resource is swept, so a thread racing to open another one is refused rather than slipping a channel past the sweep. The cost is that a resource needing the heap on its way out — a channel opened with DELETE_ON_CLOSE has a deletion to perform — finds it already gone. That is moot, since the heap is being discarded whole, and those resources tolerate it rather than failing.

Every resource is closed even if an earlier one fails, so one bad channel cannot strand the rest.

After the call:

  • a channel reports isOpen() == false and raises ClosedChannelException;

  • a directory stream raises ClosedDirectoryStreamException;

  • a watch service raises ClosedWatchServiceException;

  • anything reaching the file store raises ClosedFileSystemException.

close() is idempotent, and declares IOException: if a resource fails to close, the first failure is thrown with any others attached as suppressed exceptions, after every resource has been given its turn.

The registry holds its entries weakly. A caller who abandons a channel without closing it has leaked it already, and a long-lived default file system should not compound that by holding the remains for the life of the JVM. The corollary is that an abandoned channel may be collected before close() ever sees it, so a DELETE_ON_CLOSE deletion is only guaranteed for a channel that is actually closed — by its caller or by the file system.

  • Registration installs a heap listener on the watched directory. Registering the same directory again returns the same key with its event kinds replaced, as Watchable.register specifies, rather than handing out a second key for one directory.

  • Watching is per directory and not recursive. Heap mutations performed through the file store and the channels (createDirectory, delete, copy, move, newByteChannel with CREATE / CREATE_NEW / TRUNCATE_EXISTING, channel write / truncate) fire on the directory that contains the changed entry and on no other, so a key registered on /a says nothing about /a/b/c.txt. The WatchEvent.context() is the path relative to the watched directory.

  • Deleting a watched directory invalidates its key.

  • Polling delegates straight to the underlying queue. close() enqueues a sentinel, so a thread already blocked in take() or poll(timeout, unit) raises ClosedWatchServiceException at once.

  • A key’s pending-event queue is bounded at 512. Once it is full a single OVERFLOW event replaces what could not be kept, so a consumer that has fallen behind is told so.

  • A WatchKey that is fired while already signalled does not re-queue; subsequent fires are still added to the key’s event queue. Consumers who neglect to call reset() after pollEvents() silently stop receiving signals for that key.

EphemeralFileStore.copy(source, target, options) and move(source, target, options) both follow java.nio.file.Files semantics: the target is the destination itself, never a container to place the source inside. Both:

  • treat a target that already exists as an error unless REPLACE_EXISTING was given, and refuse to replace a directory that is not empty (DirectoryNotEmptyException);

  • require the target’s parent to exist (NoSuchFileException);

  • treat source and target naming the same file as a no-op;

  • name the result from the target’s final name.

They differ in what they do with the source:

copy

Duplicates a file’s content into a fresh HeapFileContent, charged against the capacity as a new allocation. A directory is copied as an empty directory — Files.copy copies one entry, and walking a tree is the caller’s job. COPY_ATTRIBUTES carries the timestamps over. Under NOFOLLOW_LINKS a symbolic link is copied as a link. ATOMIC_MOVE is rejected with UnsupportedOperationException.

move

Re-parents the existing node through HeapNode.relink(…​), so a directory arrives with its whole subtree intact and the cost does not depend on how much lives beneath it. A symbolic link is moved as a link, not as its target. Moving a directory beneath itself, or moving the root, is refused. ATOMIC_MOVE is accepted: a re-parent under the store’s write lock already is atomic.

getTotalSpace() reports the configured capacity; getUsableSpace() and getUnallocatedSpace() report it less the bytes currently held by file content. Only file content is charged — directories and links are not — and the count is maintained as content grows and shrinks rather than by walking the tree, so a stat call is not O(tree).

A write that would exceed the capacity fails with an IOException and changes nothing. Space is returned when a file is truncated or deleted; for a hard-linked file, only when the last name for it goes.

  • findNode follows symbolic links, and a link in any position but the last is always followed, because the elements after it have to be resolved somewhere. LinkOption.NOFOLLOW_LINKS applies to the final element only.

  • Resolution is bounded at 40 links. Beyond that a FileSystemException reports "Too many levels of symbolic links" rather than exhausting the stack.

  • A relative link target is interpreted against the directory holding the link, not against the working directory.

  • A dangling link is legal: createSymbolicLink does not require the target to exist.

  • delete removes a link rather than following it.

  • Hard links share one HeapFileContent, so both names report the same fileKey and Files.isSameFile returns true for them. Deleting one name leaves the content reachable through the other.

Every cross-path operation on a JailedPath (startsWith, endsWith, resolve, relativize, compareTo) requires the other argument to be a JailedPath. A foreign Path raises ProviderMismatchException with no message. This is a stricter contract than the JDK’s default Path types; be careful when mixing JailedPath with paths returned from other file systems.

AbstractJailedPathTranslator.asNativeName(String) vets every name element before it is appended to the native root, so a name can never contribute structure of its own. A NUL character is refused on every platform. When the native file system is backslash-separated, so are embedded separators, drive qualifiers, trailing dots or spaces, and the reserved device names (CON, PRN, AUX, NUL, CONIN$, CONOUT$, and COM0–COM9 / LPT0–LPT9). Each rejection is a SecurityException naming the offending element.

The practical consequence is that a jailed path which is perfectly legal on Linux may be refused on Windows. Names that are portable in the first place are accepted everywhere.

JailedFileSystem.newWatchService() returns a JailedWatchService wrapping the native watch service. Registering a JailedPath translates and confines it exactly as any other operation would, so a registration cannot be used to observe a directory outside the jail. The key handed back is a JailedWatchKey whose watchable() is the jailed path, and every event context is expressed in jail space, so a caller never sees a native path. JailedPath.register(…​) requires a JailedWatchService and raises ProviderMismatchException for any other watcher.

JailedFileSystemProvider.getFileStore(Path), readAttributes(…​), getFileAttributeView(…​), and setAttribute(…​) all translate the path and forward to the native provider. The returned FileStore / FileAttributeView / BasicFileAttributes instances are the native types, not jail-specific wrappers. Callers who need jail-scoped attributes (for example, a file size that is relative to an accounting quota, not the native store’s total capacity) must wrap the returned values themselves.

ProviderMismatchException

Thrown whenever an operation receives a Path whose file system is not an EphemeralFileSystem. The message identifies the offending path and the expected class. Two-argument operations (copy, move, isSameFile) also raise this exception when the two paths belong to different EphemeralFileSystem instances, with the message "The source and target are associated with different file systems".

ClosedFileSystemException

Thrown by EphemeralFileStore, EphemeralFileSystem, and EphemeralWatchService whenever a post-close method is called.

FileSystemAlreadyExistsException

Always thrown by EphemeralFileSystemProvider.newFileSystem(URI, Map). The provider pre-constructs the singleton in its constructor; callers must use getFileSystem(URI) instead.

NoSuchFileException / FileAlreadyExistsException / DirectoryNotEmptyException:: Standard NIO semantics, produced by EphemeralFileStore for the matching conditions (missing parent, existing non-REPLACE_EXISTING target, non-empty directory on delete or directory-target copy).

UnsupportedOperationException

Raised when a caller passes an open option that is neither a StandardOpenOption nor a LinkOption to newByteChannel / newFileChannel, an unrecognised CopyOption to copy / move (including ATOMIC_MOVE to copy), or a FileAttribute whose name is not "posix:permissions" to a creation method. Also raised by newAsynchronousFileChannel for an ephemeral path, by EphemeralFileChannel.map(…​), by an unsupported attribute-view name, and by getNativeFileSystem() on a provider constructed without a native provider.

IllegalArgumentException

Raised for an illegal combination of open options (APPEND with READ, or APPEND with TRUNCATE_EXISTING), for a negative channel position or size, for an unrecognised attribute name in readAttributes / setAttribute, and by EphemeralFileSystemConfiguration.checkFitToBeDefaultFileSystem() when the configuration could not serve as the JVM default.

IOException

Raised when a write would exceed the store’s capacity, with a message naming the store and the space remaining.

FileSystemException

Raised with "Too many levels of symbolic links" when link resolution exceeds 40 hops, and when a hard link is requested for something other than a regular file.

AccessDeniedException

Raised by checkAccess when AccessMode.EXECUTE is requested for anything but a directory. The heap carries no permission bits, so read and write access is always granted.

SecurityException

The single failure mode of confinement, raised with a message that identifies which rule was broken:

Message Cause

No authorization for path

No RootedFileSystemContext is present, or its root is null.

No authorization for path(=X)

The path does not lie beneath the jail root — structurally, or, under JailPolicy.STRICT, once its real location is resolved.

Illegal path element(=X) / Illegal character in path element

A name element is not a single legal name on the native file system.

Reserved path element(=X)

A name element is a reserved device name on a backslash-separated native file system.

ProviderMismatchException

Raised by any JailedPath cross-path operation that receives a non-JailedPath argument.

FileSystemAlreadyExistsException

Always thrown by JailedFileSystemProvider.newFileSystem(URI, Map).

IllegalArgumentException

Raised by JailedURIUtility for URIs that are not well-formed for the provider (wrong scheme, non-empty authority, path other than "/", any query or fragment), and by JailedPath.relativize when the two paths differ in absoluteness. Also raised when a translator is given a root that is null, not absolute, or not owned by the native file system.

Setting Default Where set

Ephemeral capacity

Long.MAX_VALUE

EphemeralFileSystemConfiguration.deriveCapacity()

Ephemeral block size

1024

EphemeralFileSystemConfiguration.deriveBlockSize()

Ephemeral roots

{"/"} (refused as the JVM default)

EphemeralFileSystemConfiguration.deriveRoots()

Ephemeral working directory

the first root

EphemeralFileSystemConfiguration.deriveWorkingDirectory()

Ephemeral provider scheme (no-arg)

"ephemeral"

EphemeralFileSystemProvider()

Ephemeral symbolic link resolution limit

40 hops

EphemeralFileStore.MAXIMUM_LINK_DEPTH

Ephemeral pending watch events per key

512, then OVERFLOW

EphemeralWatchKey.MAXIMUM_PENDING_EVENTS

Ephemeral open-resource registry

weak references

EphemeralFileSystem.openResourceSet

Jailed provider scheme (no-arg)

"jailed"

JailedFileSystemProvider()

Jailed default translator (no-arg)

ContextSensitiveRootedPathTranslator(FileSystems.getDefault())

JailedFileSystemProvider()

Jailed default policy

JailPolicy.STRICT

AbstractJailedPathTranslator(JailPolicy) subclass constructors

Jailed failure mode with no context

SecurityException("No authorization for path")

ContextSensitiveRootedPathTranslator.wrapPath / unwrapPath

Jailed path separator

'/'

JailedPath.SEPARATOR

ProviderMismatchException: The path(X) is not associated with the EphemeralFileSystem

A Path that did not come from an EphemeralFileSystem was handed to the ephemeral provider. Common cause: mixing java.nio.file.Paths.get(…​) output when the ephemeral provider is not installed as the default with a non-default ephemeral provider instance. Resolve by obtaining paths from the specific file system you intend to use (ephemeralFs.getPath(…​)).

UnsupportedOperationException: This provider(…) was constructed without a native provider

A provider constructed with the no-arg or String-scheme form has no native file system to delegate to, and a path outside the configured roots needs one. Use the EphemeralFileSystemProvider(FileSystemProvider) constructor, or ensure every path matches a configured root.

IllegalArgumentException: A root of / claims every path… at JVM start-up

The provider was named in java.nio.file.spi.DefaultFileSystemProvider without an explicit roots setting. Add -Dorg.smallmind.file.ephemeral.configuration.roots=/overlay (or whichever subtree you mean to overlay). The same refusal applies to any root that would claim java.home. See Installing as the JVM default provider.

InternalError: Error loading java.security file at JVM start-up

The overlay claimed the platform’s own files, so SecureRandom could not read java.security. If you see this, the configuration got past the check above — most likely because the roots are ephemeral-shaped but still cover the JDK (say roots=/usr on Linux). Narrow the roots.

ProviderMismatchException from an operation on a path derived from a native one

Only possible when mixing path kinds by hand. Paths derived from a NativePath stay native — resolve, resolveSibling, and relativize are all overridden to keep them so — but a path built independently through fileSystem.getPath(…​) may be an EphemeralPath. Derive from the path you already hold rather than re-parsing its text.

EphemeralFileSystem operations hang at startup under the default-provider install

Some thread is calling FileSystems.getDefault() (or Paths.get(…​)) before the provider constructor has completed. Call EphemeralFileSystemProvider.waitForInitialization(timeout, unit) from your startup path, or sequence your initialization so the provider constructs before concurrent callers run.

SecurityException("No authorization for path") in an apparently simple jailed call

The current thread has no RootedFileSystemContext in the context stack, or the context’s root is null. Push a context before the operation, and guarantee the push happens even when an exception is thrown by the path-setup code — the whole point of SecurityException here is that the jail fails closed.

SecurityException("Illegal path element(=X)") for a name that works on Linux

The native file system is backslash-separated and the name is not a legal Windows name — it embeds a separator or a drive qualifier, ends in a dot or a space, or is a reserved device name such as CON. Use portable names, which are accepted on every platform.

SecurityException("No authorization for path(=X)") on a path that looks inside the jail

Under JailPolicy.STRICT a symbolic link within the jail that resolves outside of it is refused rather than followed. That is the policy working. If the link is legitimate, either bring its target inside the jail or, having weighed the consequence, construct the translator with JailPolicy.LENIENT.

JailedPath operations reach a file outside the jail

The translator was constructed with JailPolicy.LENIENT, which applies structural confinement only and will follow a link out of the jail. Use the default JailPolicy.STRICT, and note that even STRICT cannot close the window between its check and the operation it guards — see Jail policy: structural versus real-path confinement.

IllegalArgumentException("Path component should be '/'") when obtaining a JailedFileSystem

getFileSystem(URI) was called with a URI other than "jailed:///". The path component of the URI must be exactly "/". Paths within the jail are built with fs.getPath(…​), not URIs.

No AsynchronousFileChannel, and no memory mapping, for ephemeral paths

newAsynchronousFileChannel throws UnsupportedOperationException unless the path is a NativePath, and EphemeralFileChannel.map(…​) always does: content is a list of segments, and no MappedByteBuffer can be produced over it. Code that needs mapped access must read the content into heap itself. FileChannel.open itself is supported.

Ephemeral attribute model is deliberately shallow

Only the basic view is supported. posix, dos, owner, and acl views are not implemented. setAttribute recognises only creationTime, lastModifiedTime, and lastAccessTime; any other name raises IllegalArgumentException rather than being ignored.

Ephemeral paths are POSIX-shaped on every platform

The heap namespace is rooted at / on Windows as well as Linux, which is what lets the same test address it identically on both. The corollary is that an ephemeral path is not a valid native path string on Windows, so handing path.toString() to java.io.File, to a native process, or to any API that bypasses NIO will not find the file.

Jailed confinement is by path, not by descriptor

JailPolicy.STRICT verifies a path before forwarding the operation it guards, so a link substituted in between would not be caught. Closing that window requires descriptor-relative system calls the JDK does not expose. A link already in place is reliably refused.

Jailed name validation is platform-dependent

A name element legal on Linux may be refused on a backslash-separated native file system. This is deliberate — the alternative is letting a name contribute path structure of its own — but it does mean a jail is not equally permissive everywhere.

Single-instance per provider

Both providers hold exactly one FileSystem instance. Multiple jails or multiple ephemeral overlays in the same JVM require multiple provider instances, each constructed by the application (not through the default SPI registration).

smallmind-file supplies two small, complete java.nio.file file system implementations that fill two concrete gaps in the JDK:

  • file-ephemeral gives you an in-memory FileSystem with native pass-through, links, seekable and file channels, enforced capacity, and watch support, installable as the JVM default for transparent overlay behaviour or usable side-by-side with the platform provider for tests and scratch areas.

  • file-jailed gives you a chroot-style FileSystem on top of an existing native one, with a pluggable translator strategy that supports both fixed-root and per-request root selection, and a JailPolicy that decides whether a symbolic link may be followed out of the jail.

Both modules integrate through the standard Paths, Files, and FileSystems APIs and depend on nothing outside smallmind-nutsnbolts. Pick whichever one matches the need: heap-speed storage that behaves like a real file system, or a hard boundary around a subtree of a real file system.