Skip to content

Allow symlinked local path prefix directories - #2184

Merged
cstamas merged 2 commits into
apache:masterfrom
findepi:findepi/verify-real-path-below-prefix
Oct 12, 2026
Merged

cstamas merged 2 commits into
apache:masterfrom
findepi:findepi/verify-real-path-below-prefix

Conversation

@findepi

@findepi findepi commented Oct 7, 2026

Copy link
Copy Markdown
Member

The real-path check compared the whole path below the local repository base directory with its symlink-resolved form, so any symbolic link below the base directory made every artifact beneath it "not present". This rejects layouts where a split prefix directory (e.g. the remote cache) is a symbolic link to a cache shared by several local repositories, forcing a re-download of every artifact on each build.

Only the coordinate-derived part of the path can be aliased by case-colliding coordinates; the base directory and the prefix directories come from configuration. Resolve the prefix directory and compare real(prefix directory) + coordinate path with real(full path). Case and normalization aliases in the coordinates are still rejected.


To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
check one of the following:

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Performance: prefixDirectory.toRealPath() is called on every artifact cache hit, whereas the old code resolved the real path once at construction time and stored it in realBasePath. With a warm repository holding hundreds of artifacts, every find() invocation now pays an extra filesystem syscall. In practice there are only 2–3 distinct prefix directories per session (local, release, snapshot), so their real paths could be cached.

Consider caching them similarly to the existing trackingFileCache pattern:

private final ConcurrentHashMap<Path, Path> realPathCache = new ConcurrentHashMap<>();

then replace the call with:

Path realPrefixDirectory = realPathCache.computeIfAbsent(prefixDirectory, p -> {
    try {
        return p.toRealPath();
    } catch (IOException e) {
        return p;
    }
});

This review was generated by an AI agent, HermÃĻs on behalf of @gnodet.

Comment on lines +257 to +259
String requested = prefixDirectory
.toRealPath()
.resolve(prefixDirectory.relativize(path))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ðŸ’Ą prefixDirectory.toRealPath() is invoked on every call to hasFaithfulRealPath, i.e. on every artifact cache hit. The old code computed this once at construction time (this.realBasePath = getRepository().getBasePath().toRealPath()). With only 2–3 distinct prefix directories per session, these real paths could be memoised in a ConcurrentHashMap<Path, Path> (consistent with the existing trackingFileCache pattern) to avoid repeated syscalls on warm repository builds.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, good point. Rather than caching the real paths of the prefix directories, I changed the check so it doesn't need them: it now verifies that the artifact's real path ends with the coordinate-derived path, spelled exactly as requested. That removes the extra toRealPath() call per cache hit, and there's nothing to cache. Case and normalization aliases can only occur in the coordinate part, so the protection is unchanged.

PTAL

The real-path check compared the whole path below the local repository
base directory with its symlink-resolved form, so any symbolic link
below the base directory made every artifact beneath it "not present".
This rejects layouts where a split prefix directory (e.g. the remote
cache) is a symbolic link to a cache shared by several local
repositories, forcing a re-download of every artifact on each build.

Only the coordinate-derived part of the path can be aliased by
case-colliding coordinates; the base directory and the prefix
directories come from configuration. Require the real path to end with
the coordinate-derived path, spelled exactly as requested. Case and
normalization aliases in the coordinates are still rejected.
The real-path check now resolves the prefix directory of each artifact,
so the real path of the base directory is no longer used. Without it,
the base directory does not need to exist when the manager is created,
so the constructor neither creates it nor throws IOException.
@findepi
findepi force-pushed the findepi/verify-real-path-below-prefix branch from f7e245b to 6127b99 Compare October 7, 2026 15:49

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The revised approach fully addresses the prior performance concern — rather than caching toRealPath() results for prefix directories, the new implementation eliminates the extra syscall entirely by checking that path.toRealPath() ends with the separator-prefixed, coordinate-derived relative path. This is both simpler and faster.

The endsWith(separator + requested) check is cross-platform correct: both sides use Path.toString() on the same filesystem, so the separator is consistent. The prepended separator prevents partial component matching. Edge cases (null/empty prefix returning basePath, artifact at the root of a prefix) are handled correctly.

The IOException catch in symlinkPrefixDirectory is intentional and correct — on Windows without Developer Mode or elevated privileges, Files.createSymbolicLink throws IOException (not UnsupportedOperationException), and skipping via assumeTrue(false) is the right JUnit 5 idiom.

Removing Files.createDirectories from the constructor is safe: that call existed only to satisfy the toRealPath() precondition (the directory had to exist), which is no longer needed.

Pre-fix validation (static): before the fix, realBasePath.relativize(path.toRealPath()) on a symlinked prefix would produce a path outside realBasePath (resolving through the symlink to the actual target), causing the string comparison to fail and the artifact to be spuriously rejected. The three new tests in EnhancedSplitLocalRepositoryManagerTest directly exercise this failure mode.

Metadata paths are not affected — hasFaithfulRealPath is only used in the artifact find() path, which is correct.

This review was generated by an AI agent, HermÃĻs on behalf of @gnodet.

@cstamas cstamas added this to the 2.0.25 milestone Oct 12, 2026
@cstamas cstamas added the enhancement New feature or request label Oct 12, 2026
@cstamas
cstamas merged commit 05b2e68 into apache:master Oct 12, 2026
20 checks passed
@findepi
findepi deleted the findepi/verify-real-path-below-prefix branch October 13, 2026 20:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Symbolic link within local repository directory makes every cached artifact "not present"

3 participants