You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by er...@apache.org on 2026/06/18 13:33:17 UTC
(opendal) branch rfc-path updated: rfc: rewrite path normalization RFC
This is an automated email from the ASF dual-hosted git repository.
erickguan pushed a commit to branch rfc-path
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/rfc-path by this push:
new ee66b126c rfc: rewrite path normalization RFC
ee66b126c is described below
commit ee66b126c868196a5f21edefda607847d6a02809
Author: Erick Guan <29...@users.noreply.github.com>
AuthorDate: Thu Jun 18 21:32:53 2026 +0800
rfc: rewrite path normalization RFC
Restructure the RFC to:
- broaden motivation beyond trim() to alignment with fs/object store
conventions
- combine confined_join extraction into the proposal
- replace code-level reference explanation with design rationale
- describe confined_join purpose and extraction independently of #7712
- build the problem statement in own words rather than quoting other docs
---
.../docs/rfcs/6577_preserve_whitespace_in_path.md | 441 ++++++++++-----------
1 file changed, 212 insertions(+), 229 deletions(-)
diff --git a/core/core/src/docs/rfcs/6577_preserve_whitespace_in_path.md b/core/core/src/docs/rfcs/6577_preserve_whitespace_in_path.md
index 128934186..64dad26ac 100644
--- a/core/core/src/docs/rfcs/6577_preserve_whitespace_in_path.md
+++ b/core/core/src/docs/rfcs/6577_preserve_whitespace_in_path.md
@@ -5,46 +5,81 @@
# Summary
-Remove the `.trim()` call from `normalize_path` so that whitespace within path
-components is preserved. Path normalization should only perform structural
-normalization (separator collapsing, leading-slash removal) and must not
-silently rewrite path component content.
+Remove the `.trim()` call from `normalize_path` and extract `confined_join`
+into `opendal-core` as a shared utility for local filesystem services.
+
+Together these changes make OpenDAL's path handling align with POSIX, URI, and
+object store conventions: path normalization is strictly structural (separator
+collapsing, leading-slash removal), and local-filesystem root confinement
+(rejecting `..` traversal) is a separate, explicit step available to every
+service that constructs OS paths.
# Motivation
-`normalize_path` currently calls `.trim()` on the input path before any other
-processing. This strips all leading and trailing whitespace from the entire
-path string, making files with whitespace in their names unreachable.
+OpenDAL is a storage access layer that sits between the host application and
+many kinds of backends — local filesystems, cloud object stores, databases,
+protocol services. Its path model needs to be a faithful abstraction: when a
+user passes a path, OpenDAL should deliver that path to the backend without
+silently rewriting it.
+
+## The problem: whitespace trimming
-For example, a file named `"file with trailing space "` on a local filesystem
-or an S3 object key `" report.csv"` cannot be accessed through OpenDAL because
-`normalize_path` rewrites them to different paths before the operation reaches
-the backend.
+`normalize_path` currently calls Rust's `.trim()` on the entire path string
+before any other processing. `.trim()` removes all leading and trailing Unicode
+whitespace — spaces, tabs, newlines, and exotic characters like em spaces.
+This makes objects with whitespace in their names unreachable:
```rust
normalize_path("file ") // returns "file" — a different object
normalize_path(" dir/") // returns "dir/" — a different object
```
-This violates OpenDAL's own API contract, documented in `SECURITY-THREAT-MODEL.md`
-§4.1:
+A file named `"file with trailing space "` on a local filesystem or an S3
+object key `" report.csv"` cannot be accessed through OpenDAL.
+
+## Alignment with filesystem and object store conventions
+
+Every major filesystem and object store treats whitespace in path components as
+significant content:
+
+- **POSIX filesystems** allow any byte except `/` and `\0` in filenames.
+ `"file"` and `"file "` are two distinct inodes. The POSIX Portable Filename
+ Character Set is a portability recommendation, not a filesystem restriction.
+- **S3, GCS, Azure Blob** allow arbitrary UTF-8 in object keys. Spaces are
+ listed as "characters that might require special handling" but are explicitly
+ valid. `"file"` and `"file "` are distinct objects.
+- **Rust `std::path`**, Go `filepath.Clean`, Java `Path.normalize()`, and
+ Python `pathlib` all perform structural normalization (collapsing separators,
+ resolving `.`/`..`) without touching whitespace content.
+
+The only system that strips trailing whitespace is the Win32 API, and that is a
+legacy compatibility shim from the MS-DOS 8.3 filename era — the underlying
+NTFS filesystem supports trailing spaces via the `\\?\` prefix. This is widely
+regarded as a source of bugs, not a design to emulate.
+
+OpenDAL's `.trim()` is an outlier. It goes beyond what its own path
+normalization RFC (RFC-0112) specified — that RFC defined two rules: collapse
+`//` into `/`, and strip leading `/` to make paths relative to root. The
+`.trim()` was in the implementation but was never part of the RFC's design.
-> If a host application passes a path into OpenDAL, OpenDAL must not map it to
-> a different backend location than that backend's API contract describes.
+## The problem: duplicated root confinement
-The original RFC-0112 introduced path normalization for two purposes: collapsing
-`//` into `/`, and stripping leading `/` to make paths relative to root.
-Whitespace trimming was not specified in that RFC — the implementation went
-beyond the RFC's stated scope without documented rationale.
+A separate but related issue is how local filesystem services protect against
+`..` traversal. The `fs` service has a `confined_join` function that rejects
+paths containing `..` components before joining them onto the configured root.
+The `compfs` and `monoiofs` services independently reimplemented the same logic
+as `prepare_path`. This duplication is fragile — a new filesystem service
+could easily forget to add the check.
-Every major filesystem, object store, and standard library path API treats
-whitespace in path components as significant content. Trimming it is an outlier
-behavior unique to OpenDAL.
+`confined_join` belongs in `opendal-core` as a shared utility, alongside the
+existing path functions like `build_abs_path` and `normalize_path`.
# Guide-level explanation
-After this change, `normalize_path` preserves whitespace within path
-components:
+## Path normalization preserves content
+
+After this change, `normalize_path` preserves all characters within path
+components, including whitespace:
```rust
// Before (current behavior)
@@ -65,8 +100,15 @@ The structural normalization rules remain unchanged:
- Trailing `/` is preserved to distinguish directories: `abc/` → `abc/`
- Empty path becomes `/`: `` → `/`
-Users who were relying on the trim behavior to sanitize sloppy input should
-sanitize paths in their own application code before passing them to OpenDAL:
+Since `.trim()` removes all Unicode whitespace (tabs, newlines, em spaces,
+etc.), this change preserves all of those characters too. This is correct:
+POSIX filenames can contain any byte except `/` and `\0`, and object store keys
+are arbitrary UTF-8. If a backend genuinely cannot handle certain characters,
+the service should return an error, not have the core silently rewrite the
+path.
+
+Users who relied on `.trim()` to clean up sloppy input should sanitize paths in
+their application code before passing them to OpenDAL:
```rust
// If your application needs trimmed paths, trim before calling OpenDAL:
@@ -74,184 +116,154 @@ let clean = user_input.trim();
op.read(clean).await?;
```
-OpenDAL is a storage access library, not an input sanitization layer.
-
-# Reference-level explanation
+## Root confinement for local filesystem services
-The change is a single-line removal in `core/core/src/raw/path.rs`:
+`confined_join` becomes a shared utility in `opendal_core::raw` for services
+that construct real OS paths:
```rust
-pub fn normalize_path(path: &str) -> String {
- // Before:
- // let path = path.trim().trim_start_matches('/');
- // After:
- let path = path.trim_start_matches('/');
+use opendal_core::raw::confined_join;
- if path.is_empty() {
- return "/".to_string();
- }
-
- let has_trailing = path.ends_with('/');
-
- let mut p = path
- .split('/')
- .filter(|v| !v.is_empty())
- .collect::<Vec<&str>>()
- .join("/");
-
- if has_trailing {
- p.push('/');
- }
-
- p
-}
+// In a filesystem service's Access implementation:
+let abs_path = confined_join(&self.root, path)?;
```
-The doc comment is updated to remove the whitespace trimming rule.
+This function rejects `..` traversal and joins the normalized path onto the
+configured root using `PathBuf::join`. All local filesystem services (`fs`,
+`compfs`, `monoiofs`) should use it instead of reimplementing path confinement.
-The `normalize_root` doc comment is also updated for consistency. The current
-implementation of `normalize_root` does not call `.trim()`, but its doc comment
-incorrectly claims whitespace trimming. This RFC corrects that doc comment as
-part of the change.
+# Reference-level explanation
-The existing test case `("file with whitespace", "abc/def ", "abc/def")` is
-updated to `("file with whitespace", "abc/def ", "abc/def ")`.
+## `normalize_path` change
-New test cases are added:
+Remove `.trim()` from `core/core/src/raw/path.rs`:
```rust
-("leading whitespace", " abc", " abc"),
-("trailing whitespace", "abc ", "abc "),
-("component whitespace", "a/ b /c", "a/ b /c"),
-("whitespace-only path", " ", " "),
-("whitespace dir path", " abc /", " abc /"),
+pub fn normalize_path(path: &str) -> String {
+ // Before: let path = path.trim().trim_start_matches('/');
+ // After:
+ let path = path.trim_start_matches('/');
+ // ... rest unchanged
+}
```
-## Scope of `.trim()`: all Unicode whitespace
-
-Rust's `str::trim()` removes all Unicode whitespace, not just ASCII spaces.
-This includes tabs (`\t`), newlines (`\n`, `\r`), and exotic Unicode whitespace
-(em space `\u{2003}`, etc.). After this change, all of these characters will be
-preserved in paths.
+Update the doc comment to remove the whitespace trimming rule. Also correct the
+`normalize_root` doc comment, which claims whitespace trimming but the
+implementation does not perform it.
-This is the correct behavior: POSIX filenames can contain any byte except `/`
-and `\0`. Tabs and newlines in filenames are unusual but valid. If a backend
-cannot handle certain characters, it should reject them with an error at the
-service layer, not have the core silently rewrite them.
+## `confined_join` extraction
-The fuzz test at `core/fuzz/fuzz_path.rs` already uses arbitrary `String`
-inputs, which includes these characters.
+Extract `confined_join` from `FsCore` into `opendal_core::raw::path` as a
+free function. Replace the duplicate `prepare_path` implementations in
+`compfs` and `monoiofs` with calls to this shared function.
-## Interaction with other path functions
-
-- `build_abs_path` / `build_rooted_abs_path`: concatenate root and path. No
- change needed — they are agnostic to path content.
-- `build_rel_path`: strips root prefix. No change needed.
-- `get_basename` / `get_parent`: split on `/`. No change needed — whitespace
- within components does not affect splitting.
-- `normalize_root`: does not trim whitespace today. No change needed.
-
-## Interaction with services
+```rust
+/// Join a path onto a base directory, rejecting `..` traversal and
+/// absolute path components.
+///
+/// `normalize_path` strips leading `/` and collapses empty segments, but
+/// intentionally does not resolve `.` or `..`. Since `PathBuf::join` is
+/// purely lexical, a key like `../../etc/passwd` would escape the
+/// configured root at syscall time. This function prevents that.
+///
+/// Use this function in any service that constructs real OS paths from
+/// OpenDAL paths — typically local filesystem services.
+pub fn confined_join(base: &Path, path: &str) -> Result<PathBuf> {
+ use std::path::Component;
-Services receive paths that have already been normalized by the Operator layer.
-After this change, services may receive paths with leading or trailing
-whitespace in components. This matches what the backend would see from any
-other client.
+ let trimmed = path.trim_end_matches('/');
-### Remote services (object stores, databases, protocols)
+ if trimmed.is_empty() {
+ return Ok(base.to_path_buf());
+ }
-Object stores (S3, GCS, Azure Blob, etc.) support whitespace in object keys.
-Database and KV services use arbitrary byte strings as keys. Protocol services
-(HTTP, WebDAV, FTP, SFTP) percent-encode or quote paths as needed. None of
-these services perform their own whitespace trimming on the OpenDAL path they
-receive; they pass it through to the backend via `build_abs_path` or similar.
+ let p = Path::new(trimmed);
+ if p.components().any(|c| matches!(c,
+ Component::ParentDir | Component::RootDir | Component::Prefix(_)))
+ {
+ return Err(Error::new(
+ ErrorKind::NotFound,
+ "path escapes the configured root",
+ )
+ .with_context("path", path));
+ }
-No remote service needs modification for this change.
+ Ok(base.join(trimmed))
+}
+```
-### Local filesystem services and `confined_join`
+Key design choices:
-Filesystem services (`fs`, `compfs`, `monoiofs`) are different from remote
-services because they construct real OS paths from the OpenDAL path and feed
-them to kernel syscalls. The chain is:
+- **Rejects `..` (ParentDir):** prevents traversal above the configured root.
+- **Rejects `/` (RootDir) and drive prefixes (Prefix):** prevents absolute
+ paths from replacing the base via `PathBuf::join`. The Operator's
+ `normalize_path` strips leading `/`, so this is defense-in-depth for the
+ function's own API contract.
+- **Strips trailing `/`:** avoids creating OS paths that look like directories
+ to the kernel when the OpenDAL path denotes a file. The trailing `/`
+ distinction is an OpenDAL convention for dir-vs-file; the OS path should not
+ carry it.
+- **Empty path returns the base:** consistent with how services handle the root
+ path `"/"` (which `normalize_path` represents as the empty-like `"/"`).
-```
-User path
- → normalize_path() [Operator layer — this RFC's change]
- → service.read(path) [normalized &str, no leading /]
- → confined_join(root, path) [service layer — builds PathBuf]
- → syscall(PathBuf) [kernel]
-```
-
-`confined_join` (currently on `FsCore`, being extracted to
-`opendal_core::raw` in [#7712]) rejects `..` traversal and joins the path
-onto the configured `root` using `PathBuf::join`:
+Each filesystem service keeps a thin `root_join` wrapper:
```rust
-pub fn confined_join(base: &Path, path: &str) -> Result<PathBuf> {
- let trimmed = path.trim_end_matches('/');
- if Path::new(trimmed)
- .components()
- .any(|c| matches!(c, Component::ParentDir))
- {
- return Err(/* path escapes root */);
- }
- Ok(base.join(trimmed))
+pub fn root_join(&self, path: &str) -> Result<PathBuf> {
+ confined_join(&self.root, path)
}
```
-This function is not affected by the whitespace change:
+## Interaction with existing path functions
-- `PathBuf::join` treats whitespace as literal content, matching POSIX
- semantics. `Path::new("/data").join("file ")` produces `/data/file ` — the
- correct path.
-- The `Component::ParentDir` check is unaffected — whitespace does not
- interact with `..` detection.
-- The function already strips trailing `/` via `trim_end_matches('/')` for its
- own purposes (to avoid creating paths that look like directories to the OS).
- This is distinct from the content-level `.trim()` that this RFC removes.
+- `build_abs_path` / `build_rooted_abs_path` / `build_rel_path`: string
+ concatenation, agnostic to path content. No change needed.
+- `get_basename` / `get_parent`: split on `/`. No change needed.
+- `normalize_root`: does not trim whitespace. No code change needed (doc-only).
-**Note on absolute path injection.** `PathBuf::join` replaces the base when
-given an absolute path argument. Since `normalize_path` strips all leading `/`,
-the path arriving at `confined_join` cannot be absolute — except for the
-special root path `"/"` (returned when input is empty). The current
-`confined_join` does not guard against this edge case. That is tracked
-separately in [#7712] and is orthogonal to this RFC.
+## Interaction with services
-### Guidance for service writers
+**Remote services** (S3, GCS, Azure Blob, databases, HTTP, WebDAV, FTP, etc.)
+use `build_abs_path` to construct backend keys. Whitespace passes through as
+literal content, matching the backend's own key semantics. No change needed.
-After this RFC, service writers should be aware:
+**Local filesystem services** (`fs`, `compfs`, `monoiofs`) use `confined_join`
+to construct OS paths. `PathBuf::join` treats whitespace as literal content,
+matching POSIX semantics. No change to behavior — these services already
+received whitespace-containing paths for *internal* components (e.g.,
+`"a/ b /c"` was never trimmed by `.trim()`); only leading/trailing whitespace
+on the full path string is new.
-1. **Do not trim paths yourself.** The Operator layer has already normalized
- the path. Service code should use the path as received.
+**Language bindings** (Python, Java, Node.js, etc.) pass paths through to the
+Rust core without independent normalization. This change applies uniformly.
-2. **Local filesystem services must use `confined_join`** (or its successor)
- to construct OS paths. This handles security-relevant concerns (root
- confinement, `..` rejection) that are separate from content normalization.
+## Guidance for service writers
-3. **Whitespace in path components is valid content.** On POSIX filesystems,
- `"file"` and `"file "` are distinct files. On S3, they are distinct objects.
- Services must not assume that path components are free of whitespace.
+1. **Do not trim or sanitize paths.** The Operator layer has already normalized
+ the path. Service code should use the path as received.
-4. **If a backend genuinely cannot handle whitespace**, the service should
- return a clear error rather than silently rewriting the path. No current
- OpenDAL backend has this limitation.
+2. **Use `confined_join` for local filesystem paths.** Any service that
+ constructs OS paths from OpenDAL paths should call `confined_join` to ensure
+ root confinement. Do not reimplement this check.
-### Language bindings
+3. **Whitespace in path components is valid content.** `"file"` and `"file "`
+ are distinct objects on every major backend. Do not assume components are
+ whitespace-free.
-Language bindings (Python, Java, Node.js, etc.) pass paths through to the Rust
-core without independent normalization. This change applies uniformly across
-all bindings.
+4. **Reject, don't rewrite.** If a backend cannot handle a character, return an
+ error. Silent rewriting maps one object to another, which is a data
+ correctness bug.
# Drawbacks
- **Behavior change for existing users.** Any user who relied on `normalize_path`
- to clean up sloppy whitespace in paths will see different behavior. Paths
- like `" report.csv "` were previously mapped to `"report.csv"` and will now
- be sent verbatim to the backend.
+ to clean up sloppy whitespace will see different behavior. Paths like
+ `" report.csv "` were previously mapped to `"report.csv"` and will now be
+ sent verbatim to the backend.
- **Whitespace-only paths become valid.** A path like `" "` currently maps to
- `"/"` (root) via trimming. After this change it becomes the path `" "` — a
- three-space filename. This is a valid POSIX filename but may be surprising.
+ `"/"` (root). After this change it becomes the path `" "` — a three-space
+ filename. This is a valid POSIX filename but may be surprising.
Both drawbacks are mitigated by the fact that this aligns OpenDAL with every
other path API and storage system. The previous behavior was the surprising one.
@@ -260,18 +272,18 @@ other path API and storage system. The previous behavior was the surprising one.
## Why this design
-Removing `.trim()` is the minimal change that fixes the bug. It does not
-introduce new abstractions, new configuration, or new types. It aligns OpenDAL
-with the consensus behavior of every standard path API surveyed.
+Removing `.trim()` is the minimal change that fixes the correctness bug. It
+does not introduce new abstractions, configuration, or types. Extracting
+`confined_join` eliminates code duplication and makes the security boundary for
+local filesystem services explicit and centralized.
## Alternatives considered
### Per-service path validation
-Let each service decide which characters are valid and reject unsupported paths
-explicitly. This is correct in principle but adds significant implementation
-burden across 50+ services, and the problem at hand (whitespace is
-universally valid) does not require per-service logic.
+Let each service decide which characters are valid. This is correct in
+principle but adds implementation burden across 50+ services, and the problem
+at hand (whitespace is universally valid) does not require per-service logic.
### Typed path with validation pipeline
@@ -281,99 +293,71 @@ exceeds the bug being fixed.
### Do nothing
-Leave the trim in place. Files with whitespace names remain unreachable. This
-conflicts with the documented API contract and the threat model.
-
-## Impact of not doing this
-
-Files and objects with whitespace in their names are silently mapped to
-different objects. This is a data correctness issue: users may read the wrong
-file, write to the wrong location, or get unexpected "not found" errors.
+Files with whitespace names remain unreachable. Users hit silent data
+correctness bugs.
# Prior art
-The following specifications and standard library implementations were surveyed.
-All perform structural path normalization (separator handling, `.`/`..`
-resolution). **None strip whitespace from path components.**
+The following specifications and implementations were surveyed. All perform
+structural path normalization (separator handling, `.`/`..` resolution).
+**None strip whitespace from path components.**
## POSIX.1-2017 §4.13: Pathname Resolution
-IEEE Std 1003.1-2017, published by The Open Group, defines pathname resolution
-as processing a string by splitting on `/`, resolving `.` and `..` components,
-and traversing directory entries. The only characters with special meaning in a
-pathname are `/` (separator) and `\0` (terminator). All other byte values,
-including whitespace, are treated as literal content of filename components.
-
-The POSIX Portable Filename Character Set (`A-Z a-z 0-9 . _ -`) is a
-recommendation for maximum cross-platform portability, not a filesystem
-restriction. The standard explicitly allows any byte value except `/` and `\0`
-in filenames.
+IEEE Std 1003.1-2017 defines pathname resolution by splitting on `/`, resolving
+`.` and `..`, and traversing directory entries. Only `/` (separator) and `\0`
+(terminator) have special meaning. All other bytes, including whitespace, are
+literal filename content. The POSIX Portable Filename Character Set
+(`A-Z a-z 0-9 . _ -`) is a portability recommendation, not a restriction.
Reference: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html
## RFC 3986: Uniform Resource Identifier (URI)
-RFC 3986 §6.2.2 defines syntax-based normalization for URIs. The path
-normalization rules are: remove dot segments (`.`, `..`), normalize percent-
-encoding case, and normalize scheme/host case. There is no rule to trim
-whitespace from path segments. Whitespace in URI paths is percent-encoded
-(space → `%20`), but the decoded content is preserved verbatim — a path
-containing `%20` at the end of a segment denotes a trailing space, not an empty
-suffix.
+RFC 3986 §6.2.2 defines syntax-based normalization: remove dot segments,
+normalize percent-encoding case, normalize scheme/host case. No whitespace
+trimming. Spaces are percent-encoded (`%20`), and the decoded content is
+preserved verbatim.
Reference: https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2
## Rust `std::path::Path`
-Rust's own standard library does not strip whitespace from path components.
`Path::new("file ").file_name()` returns `Some("file ")`.
-`Path::new("/a/ b /c").components()` yields `RootDir`, `Normal("a")`,
-`Normal(" b ")`, `Normal("c")` — whitespace is preserved as literal content.
-Since OpenDAL is a Rust project, its path normalization should not be more
-aggressive than the language's own path handling.
+`Path::new("/a/ b /c").components()` yields `Normal("a")`, `Normal(" b ")`,
+`Normal("c")`. Whitespace is literal content. OpenDAL's normalization should
+not be more aggressive than the language's own path handling.
Reference: https://doc.rust-lang.org/std/path/struct.Path.html
-## Go `filepath.Clean` and `path.Clean`
+## Go `filepath.Clean`
-Go's `filepath.Clean` applies four rules: (1) replace multiple separators with
-one, (2) eliminate `.`, (3) eliminate inner `..`, (4) eliminate root `..`.
-Whitespace is not mentioned and is preserved verbatim. `filepath.Clean("file ")
-` returns `"file "`.
+Applies four rules: collapse separators, eliminate `.`, eliminate inner `..`,
+eliminate root `..`. Whitespace is preserved. `filepath.Clean("file ")` returns
+`"file "`.
Reference: https://pkg.go.dev/path/filepath#Clean
## Java `java.nio.file.Path.normalize()`
-Java's `Path.normalize()` eliminates redundant `.` and `..` name elements. The
-specification states: "The precise definition of this method is implementation
-dependent but in general it derives from this path, a path that does not
-contain redundant name elements." No implementation trims whitespace from path
-components. `Paths.get("file ").normalize()` returns `"file "`.
+Eliminates redundant `.` and `..` name elements. No whitespace trimming.
+`Paths.get("file ").normalize()` returns `"file "`.
Reference: https://docs.oracle.com/javase/8/docs/api/java/nio/file/Path.html#normalize--
## AWS S3 Object Key Naming
-S3 object keys are sequences of Unicode characters (UTF-8, max 1024 bytes).
-Space is listed under "characters that might require special handling" but is
-explicitly allowed. Leading and trailing spaces in keys are semantically
-significant — `"file"` and `"file "` are distinct objects. S3 does not perform
-any whitespace normalization on keys.
+Object keys are UTF-8, max 1024 bytes. Spaces are explicitly allowed. Leading
+and trailing spaces are semantically significant — `"file"` and `"file "` are
+distinct objects.
Reference: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html
## Win32 Path Normalization (counterexample)
-The Win32 API strips trailing spaces and periods from filenames during its path
-normalization step. However, this is a legacy compatibility behavior inherited
-from the MS-DOS 8.3 filename era, not a deliberate design choice. The
-underlying NTFS filesystem supports trailing spaces — they are accessible via
-the `\\?\` prefix that bypasses Win32 normalization. Microsoft's own
-documentation warns: "Do not end a file or directory name with a space or a
-period." This is acknowledged as a UI/API limitation, not a filesystem one.
-
-OpenDAL should not emulate this legacy behavior.
+The Win32 API strips trailing spaces and periods — a legacy behavior from
+MS-DOS 8.3 filenames. NTFS itself supports them via `\\?\`. Microsoft's docs
+acknowledge this as a UI limitation. OpenDAL should not emulate it.
Reference: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
@@ -383,8 +367,7 @@ None.
# Future possibilities
-- **Path validation layer.** A future RFC could introduce an optional validation
- layer that rejects paths with characters problematic for specific backends
- (e.g., control characters, excessively long components). This would be
- explicit rejection with an error, not silent rewriting — a fundamentally
- different approach from trimming.
+- **Path validation layer.** A future RFC could introduce an optional layer that
+ rejects paths with characters problematic for specific backends (control
+ characters, excessively long components). This would be explicit rejection
+ with an error — fundamentally different from silent rewriting.