1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
|
// Copyright (C) 2016 The Syncthing Authors.
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this file,
// You can obtain one at https://mozilla.org/MPL/2.0/.
package fs
import (
"context"
"errors"
"io"
"io/fs"
"os"
"path/filepath"
"strings"
"time"
"github.com/syncthing/syncthing/lib/protocol"
)
type filesystemWrapperType int32
const (
filesystemWrapperTypeNone filesystemWrapperType = iota
filesystemWrapperTypeMtime
filesystemWrapperTypeCase
filesystemWrapperTypeError
filesystemWrapperTypeWalk
filesystemWrapperTypeLog
filesystemWrapperTypeMetrics
)
type XattrFilter interface {
Permit(string) bool
GetMaxSingleEntrySize() int
GetMaxTotalSize() int
}
// The Filesystem interface abstracts access to the file system.
type Filesystem interface {
Chmod(name string, mode FileMode) error
Lchown(name string, uid, gid string) error // uid/gid as strings; numeric on POSIX, SID on Windows, like in os/user package
Chtimes(name string, atime time.Time, mtime time.Time) error
Create(name string) (File, error)
CreateSymlink(target, name string) error
DirNames(name string) ([]string, error)
Lstat(name string) (FileInfo, error)
Mkdir(name string, perm FileMode) error
MkdirAll(name string, perm FileMode) error
Open(name string) (File, error)
OpenFile(name string, flags int, mode FileMode) (File, error)
ReadSymlink(name string) (string, error)
Remove(name string) error
RemoveAll(name string) error
Rename(oldname, newname string) error
Stat(name string) (FileInfo, error)
SymlinksSupported() bool
Walk(name string, walkFn WalkFunc) error
// If setup fails, returns non-nil error, and if afterwards a fatal (!)
// error occurs, sends that error on the channel. Afterwards this watch
// can be considered stopped.
Watch(path string, ignore Matcher, ctx context.Context, ignorePerms bool) (<-chan Event, <-chan error, error)
Hide(name string) error
Unhide(name string) error
Glob(pattern string) ([]string, error)
Roots() ([]string, error)
Usage(name string) (Usage, error)
Type() FilesystemType
URI() string
Options() []Option
SameFile(fi1, fi2 FileInfo) bool
PlatformData(name string, withOwnership, withXattrs bool, xattrFilter XattrFilter) (protocol.PlatformData, error)
GetXattr(name string, xattrFilter XattrFilter) ([]protocol.Xattr, error)
SetXattr(path string, xattrs []protocol.Xattr, xattrFilter XattrFilter) error
// Used for unwrapping things
underlying() (Filesystem, bool)
wrapperType() filesystemWrapperType
}
// The File interface abstracts access to a regular file, being a somewhat
// smaller interface than os.File
type File interface {
io.Closer
io.Reader
io.ReaderAt
io.Seeker
io.Writer
io.WriterAt
Name() string
Truncate(size int64) error
Stat() (FileInfo, error)
Sync() error
}
// The FileInfo interface is almost the same as os.FileInfo, but with the
// Sys method removed (as we don't want to expose whatever is underlying)
// and with a couple of convenience methods added.
type FileInfo interface {
// Standard things present in os.FileInfo
Name() string
Mode() FileMode
Size() int64
ModTime() time.Time
IsDir() bool
Sys() interface{}
// Extensions
IsRegular() bool
IsSymlink() bool
Owner() int
Group() int
InodeChangeTime() time.Time // may be zero if not supported
}
// FileMode is similar to os.FileMode
type FileMode uint32
func (fm FileMode) String() string {
return os.FileMode(fm).String()
}
// Usage represents filesystem space usage
type Usage struct {
Free uint64
Total uint64
}
type Matcher interface {
ShouldIgnore(name string) bool
SkipIgnoredDirs() bool
}
type MatchResult interface {
IsIgnored() bool
}
type Event struct {
Name string
Type EventType
}
type EventType int
const (
NonRemove EventType = 1 + iota
Remove
Mixed // Should probably not be necessary to be used in filesystem interface implementation
)
// Merge returns Mixed, except if evType and other are the same and not Mixed.
func (evType EventType) Merge(other EventType) EventType {
return evType | other
}
func (evType EventType) String() string {
switch {
case evType == NonRemove:
return "non-remove"
case evType == Remove:
return "remove"
case evType == Mixed:
return "mixed"
default:
panic("bug: Unknown event type")
}
}
var (
ErrWatchNotSupported = errors.New("watching is not supported")
ErrXattrsNotSupported = errors.New("extended attributes are not supported on this platform")
)
// Equivalents from os package.
const (
ModePerm = FileMode(os.ModePerm)
ModeSetgid = FileMode(os.ModeSetgid)
ModeSetuid = FileMode(os.ModeSetuid)
ModeSticky = FileMode(os.ModeSticky)
ModeSymlink = FileMode(os.ModeSymlink)
ModeType = FileMode(os.ModeType)
PathSeparator = os.PathSeparator
OptAppend = os.O_APPEND
OptCreate = os.O_CREATE
OptExclusive = os.O_EXCL
OptReadOnly = os.O_RDONLY
OptReadWrite = os.O_RDWR
OptSync = os.O_SYNC
OptTruncate = os.O_TRUNC
OptWriteOnly = os.O_WRONLY
)
// SkipDir is used as a return value from WalkFuncs to indicate that
// the directory named in the call is to be skipped. It is not returned
// as an error by any function.
var SkipDir = filepath.SkipDir
func IsExist(err error) bool {
return errors.Is(err, ErrExist)
}
// ErrExist is the equivalent of os.ErrExist
var ErrExist = fs.ErrExist
// IsNotExist is the equivalent of os.IsNotExist
func IsNotExist(err error) bool {
return errors.Is(err, ErrNotExist)
}
// ErrNotExist is the equivalent of os.ErrNotExist
var ErrNotExist = fs.ErrNotExist
// IsPermission is the equivalent of os.IsPermission
func IsPermission(err error) bool {
return errors.Is(err, fs.ErrPermission)
}
// IsPathSeparator is the equivalent of os.IsPathSeparator
var IsPathSeparator = os.IsPathSeparator
// Option modifies a filesystem at creation. An option might be specific
// to a filesystem-type.
//
// String is used to detect options with the same effect, i.e. must be different
// for options with different effects. Meaning if an option has parameters, a
// representation of those must be part of the returned string.
type Option interface {
String() string
apply(Filesystem) Filesystem
}
func NewFilesystem(fsType FilesystemType, uri string, opts ...Option) Filesystem {
var caseOpt Option
var mtimeOpt Option
i := 0
for _, opt := range opts {
if caseOpt != nil && mtimeOpt != nil {
break
}
switch opt.(type) {
case *OptionDetectCaseConflicts:
caseOpt = opt
case *optionMtime:
mtimeOpt = opt
default:
opts[i] = opt
i++
}
}
opts = opts[:i]
var fs Filesystem
switch fsType {
case FilesystemTypeBasic:
fs = newBasicFilesystem(uri, opts...)
case FilesystemTypeFake:
fs = newFakeFilesystem(uri, opts...)
default:
l.Debugln("Unknown filesystem", fsType, uri)
fs = &errorFilesystem{
fsType: fsType,
uri: uri,
err: errors.New("filesystem with type " + fsType.String() + " does not exist."),
}
}
// Case handling is the innermost, as any filesystem calls by wrappers should be case-resolved
if caseOpt != nil {
fs = caseOpt.apply(fs)
}
// mtime handling should happen inside walking, as filesystem calls while
// walking should be mtime-resolved too
if mtimeOpt != nil {
fs = mtimeOpt.apply(fs)
}
fs = &metricsFS{next: fs}
if l.ShouldDebug("walkfs") {
return NewWalkFilesystem(&logFilesystem{fs})
}
if l.ShouldDebug("fs") {
return &logFilesystem{NewWalkFilesystem(fs)}
}
return NewWalkFilesystem(fs)
}
// IsInternal returns true if the file, as a path relative to the folder
// root, represents an internal file that should always be ignored. The file
// path must be clean (i.e., in canonical shortest form).
func IsInternal(file string) bool {
// fs cannot import config or versioner, so we hard code .stfolder
// (config.DefaultMarkerName) and .stversions (versioner.DefaultPath)
internals := []string{".stfolder", ".stignore", ".stversions"}
for _, internal := range internals {
if file == internal {
return true
}
if IsParent(file, internal) {
return true
}
}
return false
}
var (
errPathInvalid = errors.New("path is invalid")
errPathTraversingUpwards = errors.New("relative path traversing upwards (starting with ..)")
)
// Canonicalize checks that the file path is valid and returns it in the "canonical" form:
// - /foo/bar -> foo/bar
// - / -> "."
func Canonicalize(file string) (string, error) {
const pathSep = string(PathSeparator)
if strings.HasPrefix(file, pathSep+pathSep) {
// The relative path may pretend to be an absolute path within
// the root, but the double path separator on Windows implies
// something else and is out of spec.
return "", errPathInvalid
}
// The relative path should be clean from internal dotdots and similar
// funkyness.
file = filepath.Clean(file)
// It is not acceptable to attempt to traverse upwards.
if file == ".." {
return "", errPathTraversingUpwards
}
if strings.HasPrefix(file, ".."+pathSep) {
return "", errPathTraversingUpwards
}
if strings.HasPrefix(file, pathSep) {
if file == pathSep {
return ".", nil
}
return file[1:], nil
}
return file, nil
}
// unwrapFilesystem removes "wrapping" filesystems to expose the filesystem of the requested wrapperType, if it exists.
func unwrapFilesystem(fs Filesystem, wrapperType filesystemWrapperType) (Filesystem, bool) {
var ok bool
for {
if fs.wrapperType() == wrapperType {
return fs, true
}
fs, ok = fs.underlying()
if !ok {
return nil, false
}
}
}
// WriteFile writes data to the named file, creating it if necessary.
// If the file does not exist, WriteFile creates it with permissions perm (before umask);
// otherwise WriteFile truncates it before writing, without changing permissions.
// Since Writefile requires multiple system calls to complete, a failure mid-operation
// can leave the file in a partially written state.
func WriteFile(fs Filesystem, name string, data []byte, perm FileMode) error {
f, err := fs.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, perm)
if err != nil {
return err
}
_, err = f.Write(data)
if err1 := f.Close(); err1 != nil && err == nil {
err = err1
}
return err
}
|