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.