refactor: extract confined_join

[erickguan]

Which issue does this PR close?

Complement to #7702. Merge after #7702

Rationale for this change

Better code cohesion and documentation.

What changes are included in this PR?

• extraction of confined_join

Are there any user-facing changes?

None

AI Usage Statement

No

[tonghuaroot]

confined_join rejects .. traversal but does not guard against absolute paths. On Unix, PathBuf::join with an absolute argument replaces the base entirely:

let base = Path::new("/data/root");
assert_eq!(base.join("/etc/passwd"), Path::new("/etc/passwd")); // escapes root

I know normalize_path strips the leading / before keys reach the backend, but since confined_join is now a public API in core, it would be safer to also reject Component::RootDir (and Component::Prefix on Windows) so the function is self-contained and doesn't rely on callers to sanitize input.

[erickguan]

@tonghuaroot Good point! Anything in core/src/raw are private APIs subject to our changes. We apply normalize_path in Operator before a service sees the path. But I can see confined_join rather confusing for service maintainers.

From OpenDAL users perspective, trying something with "/etc/passwd" should never work when root is /root:

let op = Operator::new("fs", "/root")?.finish(); # pesudo code
op.read("/etc/passwd").await?; # We don't have access to this file.

normalize_path strips the leading / before keys reach the backend

normalize_path has a corner case which will return "/" when path is empty. This will also break the confined_join as you pointed out PathBuf::join will replace path with an absolute path. So a safer choice would be to reject absolute path except "/".

    let trimmed = path.trim_end_matches('/');
    if trimmed == "" {
        return Ok(base)
    }
    if Path::new(trimmed)
        .components()
        .any(|c| matches!(c, Component::ParentDir))
    {
        return Err(Error::new(
            ErrorKind::NotFound,
            "path escapes the configured root via `..`",
        )
        .with_context("path", path));
    }
    Ok(base.join(normalized))
}

Another problem is that we are losing information from this API. e.g. when we have a path dir/, our function strips the information. I believe some services rely on the trailing / so this is still not of satisfactory.

[erickguan]

Let's wait #7641 to see what do we want to do.
E.g., could return a path; could simply validate.

[tonghuaroot]

These tests (test_root_join_rejects_parent_dir / test_root_join_allows_normal_keys) are near-identical to the test_confined_join_* tests already added in path.rs. Since root_join is a one-line wrapper over confined_join, this duplicates coverage. Consider keeping only the path.rs tests to avoid maintaining two copies.

[erickguan]

Yes! Merged.

[tonghuaroot]

#7641 is merged now. The empty-path "/" case you mentioned is another good catch. Happy to help if you'd like me to send a follow-up PR for the absolute path guard.

[erickguan]

@tonghuaroot Sounds good! Can you open a new PR after this one?

[tonghuaroot]

LGTM on the refactoring. Will open a follow-up PR for the absolute path guard after this lands.