|
| 1 | +/* |
| 2 | + Copyright The containerd Authors. |
| 3 | +
|
| 4 | + Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + you may not use this file except in compliance with the License. |
| 6 | + You may obtain a copy of the License at |
| 7 | +
|
| 8 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +
|
| 10 | + Unless required by applicable law or agreed to in writing, software |
| 11 | + distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + See the License for the specific language governing permissions and |
| 14 | + limitations under the License. |
| 15 | +*/ |
| 16 | + |
| 17 | +/* |
| 18 | +Package atomicfile provides a mechanism (on Unix-like platforms) to present a consistent view of a file to separate |
| 19 | +processes even while the file is being written. This is accomplished by writing a temporary file, syncing to disk, and |
| 20 | +renaming over the destination file name. |
| 21 | +
|
| 22 | +Partial/inconsistent reads can occur due to: |
| 23 | + 1. A process attempting to read the file while it is being written to (both in the case of a new file with a |
| 24 | + short/incomplete write or in the case of an existing, updated file where new bytes may be written at the beginning |
| 25 | + but old bytes may still be present after). |
| 26 | + 2. Concurrent goroutines leading to multiple active writers of the same file. |
| 27 | +
|
| 28 | +The above mechanism explicitly protects against (1) as all writes are to a file with a temporary name. |
| 29 | +
|
| 30 | +There is no explicit protection against multiple, concurrent goroutines attempting to write the same file. However, |
| 31 | +atomically writing the file should mean only one writer will "win" and a consistent file will be visible. |
| 32 | +
|
| 33 | +Note: atomicfile is partially implemented for Windows. The Windows codepath performs the same operations, however |
| 34 | +Windows does not guarantee that a rename operation is atomic; a crash in the middle may leave the destination file |
| 35 | +truncated rather than with the expected content. |
| 36 | +*/ |
| 37 | +package atomicfile |
| 38 | + |
| 39 | +import ( |
| 40 | + "errors" |
| 41 | + "fmt" |
| 42 | + "io" |
| 43 | + "os" |
| 44 | + "path/filepath" |
| 45 | + "sync" |
| 46 | +) |
| 47 | + |
| 48 | +// File is an io.ReadWriteCloser that can also be Canceled if a change needs to be abandoned. |
| 49 | +type File interface { |
| 50 | + io.ReadWriteCloser |
| 51 | + // Cancel abandons a change to a file. This can be called if a write fails or another error occurs. |
| 52 | + Cancel() error |
| 53 | +} |
| 54 | + |
| 55 | +// ErrClosed is returned if Read or Write are called on a closed File. |
| 56 | +var ErrClosed = errors.New("file is closed") |
| 57 | + |
| 58 | +// New returns a new atomic file. On Unix-like platforms, the writer (an io.ReadWriteCloser) is backed by a temporary |
| 59 | +// file placed into the same directory as the destination file (using filepath.Dir to split the directory from the |
| 60 | +// name). On a call to Close the temporary file is synced to disk and renamed to its final name, hiding any previous |
| 61 | +// file by the same name. |
| 62 | +// |
| 63 | +// Note: Take care to call Close and handle any errors that are returned. Errors returned from Close may indicate that |
| 64 | +// the file was not written with its final name. |
| 65 | +func New(name string, mode os.FileMode) (File, error) { |
| 66 | + return newFile(name, mode) |
| 67 | +} |
| 68 | + |
| 69 | +type atomicFile struct { |
| 70 | + name string |
| 71 | + f *os.File |
| 72 | + closed bool |
| 73 | + closedMu sync.RWMutex |
| 74 | +} |
| 75 | + |
| 76 | +func newFile(name string, mode os.FileMode) (File, error) { |
| 77 | + dir := filepath.Dir(name) |
| 78 | + f, err := os.CreateTemp(dir, "") |
| 79 | + if err != nil { |
| 80 | + return nil, fmt.Errorf("failed to create temp file: %w", err) |
| 81 | + } |
| 82 | + if err := f.Chmod(mode); err != nil { |
| 83 | + return nil, fmt.Errorf("failed to change temp file permissions: %w", err) |
| 84 | + } |
| 85 | + return &atomicFile{name: name, f: f}, nil |
| 86 | +} |
| 87 | + |
| 88 | +func (a *atomicFile) Close() (err error) { |
| 89 | + a.closedMu.Lock() |
| 90 | + defer a.closedMu.Unlock() |
| 91 | + |
| 92 | + if a.closed { |
| 93 | + return nil |
| 94 | + } |
| 95 | + a.closed = true |
| 96 | + |
| 97 | + defer func() { |
| 98 | + if err != nil { |
| 99 | + _ = os.Remove(a.f.Name()) // ignore errors |
| 100 | + } |
| 101 | + }() |
| 102 | + // The order of operations here is: |
| 103 | + // 1. sync |
| 104 | + // 2. close |
| 105 | + // 3. rename |
| 106 | + // While the ordering of 2 and 3 is not important on Unix-like operating systems, Windows cannot rename an open |
| 107 | + // file. By closing first, we allow the rename operation to succeed. |
| 108 | + if err = a.f.Sync(); err != nil { |
| 109 | + return fmt.Errorf("failed to sync temp file %q: %w", a.f.Name(), err) |
| 110 | + } |
| 111 | + if err = a.f.Close(); err != nil { |
| 112 | + return fmt.Errorf("failed to close temp file %q: %w", a.f.Name(), err) |
| 113 | + } |
| 114 | + if err = os.Rename(a.f.Name(), a.name); err != nil { |
| 115 | + return fmt.Errorf("failed to rename %q to %q: %w", a.f.Name(), a.name, err) |
| 116 | + } |
| 117 | + return nil |
| 118 | +} |
| 119 | + |
| 120 | +func (a *atomicFile) Cancel() error { |
| 121 | + a.closedMu.Lock() |
| 122 | + defer a.closedMu.Unlock() |
| 123 | + |
| 124 | + if a.closed { |
| 125 | + return nil |
| 126 | + } |
| 127 | + a.closed = true |
| 128 | + _ = a.f.Close() // ignore error |
| 129 | + return os.Remove(a.f.Name()) |
| 130 | +} |
| 131 | + |
| 132 | +func (a *atomicFile) Read(p []byte) (n int, err error) { |
| 133 | + a.closedMu.RLock() |
| 134 | + defer a.closedMu.RUnlock() |
| 135 | + if a.closed { |
| 136 | + return 0, ErrClosed |
| 137 | + } |
| 138 | + return a.f.Read(p) |
| 139 | +} |
| 140 | + |
| 141 | +func (a *atomicFile) Write(p []byte) (n int, err error) { |
| 142 | + a.closedMu.RLock() |
| 143 | + defer a.closedMu.RUnlock() |
| 144 | + if a.closed { |
| 145 | + return 0, ErrClosed |
| 146 | + } |
| 147 | + return a.f.Write(p) |
| 148 | +} |
0 commit comments