io/fs: add more specific documentation about valid paths #44168
Labels
Documentation
Issues describing a change to documentation.
NeedsInvestigation
Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
What version of Go are you using (
go version
)?Does this issue reproduce with the latest release?
What operating system and processor architecture are you using (
go env
)?go env
OutputWe are early adopters of
io/fs
: we'd been wanting to move to a VFS implementation and the original proposal gave us the push to do so. So far, it has been a good decision. It's allowed us to stub out the file system implementation for tests (SlowFS
,CorruptedFS
, etc.), to more easily test bugs by replaying application state from ZIP files, and to transparently encrypt files.One pain point, however, is knowing what constitutes a valid file path for a particular
FS
. With theos
package, we could make a reasonable set of assumptions. For example, rejecting or not creating paths with problematic or illegal characters like null bytes or rejecting or not creating excessively long paths. But withio/fs
, we can't. It's impossible to know whether theFS
isos.DirFS
, a remote object store, or an in-memory file system.There seem to be two possibly correct answers:
FS
must accept any path for whichValidPath
returns true and therefore translate it accordinglyio/fs
must document what it expects out of theFS
The implementation of
os.DirFS
seems to assume (2), but it's not clearly documented.ValidPath
should more clearly document its assumptions.Relates to #44166.
The text was updated successfully, but these errors were encountered: