fs: ValidPath() docs seem to contradict test case regarding "."

[mholt]

Go version

go version go1.23.2 linux/amd64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='amd64'
GOBIN=''
GOCACHE='/home/matt/.cache/go-build'
GOENV='/home/matt/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMODCACHE='/home/matt/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='/home/matt/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/lib/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/lib/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.23.2'
GODEBUG=''
GOTELEMETRY='on'
GOTELEMETRYDIR='/home/matt/.config/go/telemetry'
GCCGO='gccgo'
GOAMD64='v1'
AR='ar'
CC='gcc'
CXX='g++'
CGO_ENABLED='1'
GOMOD='/home/matt/Dev/archiver/go.mod'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build3734862726=/tmp/go-build -gno-record-gcc-switches'

What did you do?

func (f *ArchiveFS) Open(name string) (fs.File, error) {
	if !fs.ValidPath(name) {
		return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrInvalid}
	}

Trying to implement fs.FS with the use of fs.ValidName().

What did you see happen?

A path of ./foo is rejected, even though a file system literally has a root directory named ".", and the docs for fs.ValidPath() state (emphasis mine):

Path names must not contain an element that is “.” or “..” or the empty string, except for the special case that the root directory is named “.”.

Here, the root directory is named ".", and the docs say that should be an exception that is allowed. Yet the test case seems to show otherwise: {"./x", false},

What did you expect to see?

I might be reading the docs wrong, but it seems like this should be allowed, especially since there are virtual file systems (like a tar archive) where there are literally root directories named "." (this can happen apparently when a tar archive is created in the same directory it is archiving).

[gabyhelp]

Related Issues and Documentation

• io/fs,os: fs.ReadDir with an os.DirFS can produce invalid paths #44166 (closed)
• io/fs: add more specific documentation about valid paths #44168
• testing/fstest TestFS rejects an FS that can read file.txt and /file.txt interchangeably #45397 (closed)
• io/fs: SubFS.Open returns incorrect errors for invalid paths #65419 (closed)
• testing/testfs: tests including absolute root-based paths fail #51378 (closed)
• Package fs > func ValidPath ¶ 1.16
• io/fs: should fs.Sub(fsys, "no such directory") return a file system that fails fstest.TestFS? #45087
• os: os.DirFS doesn't work with Windows UNC paths #54694 (closed)
• io/fs: allow backslash in ValidPath, reject in os.DirFS.Open
• os: dirFS.ReadFile returns inconsistent PathError.Path #64366 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

It allows for Open(".") and nothing else. Any path such as ./foo should be just foo

[mholt]

Thanks but that doesn't really address my questions.

Can the docs be reworded then? Because ./foo complies with what is allowed currently.

Also what about a directory that is literally named .? How is one supposed to specify that?

[ianlancetaylor]

Directories literally named . (other than the root directory) are not supported (nor are directories literally named ..).

You are reading the docs wrong. You are not permitted to refer to a directory as . except for one single special case: opening the root directory, which you can do with the name ".".

[mholt]

Okay, thanks for clarifying. Maybe the doc could be reworded/clarified, that it's referring to the root of the file system, not a folder in the root named ".".

This policy still leaves us with the problem of what to do about literal files named "." as appear in some tar archives (for example: request your user data from GitHub, and the downloaded tar has a "." folder in its root). Deciding that it's "not supported" or "not permitted" seems arbitrary when there are folders/files named ".". Is there a technical reason that this limitation exists, or is it just because we like clean paths?

[ianlancetaylor]

The technical reason is that the io/fs package is providing an abstraction of a simple unrooted file system. By not permitting names like . we avoid confusion over the fact that in a Unix file system dir and dir/. name the same entity.

The expectation is that translation from some other file system to io/fs will clean paths as necessary. If a tar archive contains a file ./x, then presenting an io/fs view of that tar archive will read ./x as x. So I don't quite see the problem you are describing.

[mholt]

The problem is an archive that looks like:

x
.
./x

now becomes untenable because this restriction in io/fs forces us to treat ./x as x, which conflicts with x.

[ianlancetaylor]

In that tree are x and ./x intended to be different files? That is a hierarchy that can't be represented directly in io/fs, nor, for that matter, in a Unix file system.

[mholt]

Yep. I agree, that's just how it is though. (Perhaps the tar utility is to blame.)

Anyway, I will try to find a work around. (But I still recommend a clarification of the docs)

[gopherbot]

Change https://go.dev/cl/624595 mentions this issue: io/fs: clarify that "." may only be used for root

[mholt]

Looks good. 👍 Thank you!