filesystem

Documentation

Index

• Variables
• func CopyToFileWithRename(filename string, reader io.Reader, dataSize int64, perm os.FileMode, ...) (err error)
• func GetUmask() uint32
• func Lock(path string) (file *os.File, err error)
• func ReadFile(filename string) (data []byte, err error)
• func ReadOnlyLock(path string) (file *os.File, err error)
• func SetFilesystemOpsDirectory(path string) error
• func Stat(filename string) (os.FileInfo, error)
• func Unlock(lock *os.File) error
• func ValidatePathComponent(pathComponent string) error
• func WithLock(path string, function func() error) (err error)
• func WithReadOnlyLock(path string, function func() error) (err error)
• func WriteFile(filename string, data []byte, perm os.FileMode) error
• func WriteFileWithRename(filename string, data []byte, perm os.FileMode) error
• func WriteFileWithRollback(filename string, data []byte, perm os.FileMode) (rollback func() error, err error)

Variables

var (
	ErrLockFail          = errors.New("failed to acquire lock")
	ErrUnlockFail        = errors.New("failed to release lock")
	ErrLockIsNil         = errors.New("nil lock")
	ErrInvalidPath       = errors.New("invalid path")
	ErrFilesystemFailure = errors.New("filesystem error")
)

Functions

func CopyToFileWithRename

func CopyToFileWithRename(filename string, reader io.Reader, dataSize int64, perm os.FileMode, mTime time.Time) (err error)

CopyToFileWithRename is an atomic wrapper around io.Copy(file, reader). See notes above in WriteFile for details.

func GetUmask

func GetUmask() uint32

GetUmask retrieves the current umask.

func Lock

func Lock(path string) (file *os.File, err error)

Lock places an advisory write lock on the file, blocking until it can be locked.

If Lock returns nil, no other process will be able to place a read or write lock on the file until this process exits, closes f, or calls Unlock on it.

func ReadFile

func ReadFile(filename string) (data []byte, err error)

func ReadOnlyLock

func ReadOnlyLock(path string) (file *os.File, err error)

ReadOnlyLock places an advisory read lock on the file, blocking until it can be locked.

If ReadOnlyLock returns nil, no other process will be able to place a write lock on the file until this process exits, closes f, or calls Unlock on it.

func SetFilesystemOpsDirectory

func SetFilesystemOpsDirectory(path string) error

func Stat

func Stat(filename string) (os.FileInfo, error)

func Unlock

func Unlock(lock *os.File) error

Unlock removes an advisory lock placed on f by this process.

func ValidatePathComponent

func ValidatePathComponent(pathComponent string) error

ValidatePathComponent will enforce os specific filename restrictions on a single path component.

func WithLock

func WithLock(path string, function func() error) (err error)

WithLock executes the provided function after placing a write lock on `path`. The lock is released once the function has been run, regardless of outcome.

func WithReadOnlyLock

func WithReadOnlyLock(path string, function func() error) (err error)

WithReadOnlyLock executes the provided function after placing a read lock on `path`. The lock is released once the function has been run, regardless of outcome.

func WriteFile

func WriteFile(filename string, data []byte, perm os.FileMode) error

WriteFile implements an atomic and durable alternative to os.WriteFile that does not change inodes (unlike the usual approach on atomic writes that relies on renaming files).

func WriteFileWithRename

func WriteFileWithRename(filename string, data []byte, perm os.FileMode) error

WriteFileWithRename is a drop-in replacement for os.WriteFile, with the same signature and almost identical behavior (see note below on inodes). Unlike os.WriteFile, it does provide extra guarantees: - Atomicity (provided by rename - *mostly* atomic, except on OS crash, where rename behavior is undefined) - Durability (sync-ed) Note that: - this does not provide Isolation (a locking mechanism needs to be used independently to enforce that) - Consistency is orthogonal here, and high-level operations that expect it across a set of unrelated ops need to implement locking, rollback, and disaster recovery - this will change inode in case the file already exist - therefore, there are cases where this cannot be used (specifically if a file is mounted inside a container) - these are the exception though, and in almost all cases, this method should be preferred over os.WriteFile Finally note that we do not do anything smart wrt symlinks. User is expected to resolve symlink for the destination before calling this if needed.

func WriteFileWithRollback

func WriteFileWithRollback(filename string, data []byte, perm os.FileMode) (rollback func() error, err error)

WriteFileWithRollback implements an atomic and durable file write operation with rollback. The rollback callback may be called by higher-level operations in case there is a need to revert changes as part of a more complex, multi-prong operation. Note that with or without rollback, WriteFileWithRollback does ensure disaster recovery.