fs

Overview ¶

Package fs implements blob.Store on a local directory tree. It is the "no bucket" storage option and the target of `backyard deploy --method rsync`, and also works on top of mounted buckets (gcsfuse, blobfuse2; see below for mountpoint-s3).

Keys map to files below the root directory ("sites/foo/index.html" → <root>/sites/foo/index.html). All access goes through os.Root handles, so no operation can reach outside the root. Beyond that, every directory on a key's path is opened one component at a time and must be a real directory (verified against its Lstat result); files are then created, renamed, read and removed by name relative to that directory handle. A concurrent writer below the root (e.g. a racing rsync) that swaps a directory for a symlink therefore cannot redirect a write, read or delete to another part of the tree (such as a database file kept in the root).

Writes are atomic: data is written to a hidden temporary file in the destination directory and renamed into place. Path segments starting with ".backyard-tmp-" are reserved for these files: such keys are rejected with blob.ErrInvalidKey and such entries are hidden from List.

Because files may be written by tools other than Backyard (rsync), object metadata is derived from the file itself:

• ETag is a hash of size and modification time (nanoseconds), so it changes whenever rsync replaces a file. Put sets a fresh, unique mtime.
• Content type comes from blob.DetectContentType (extension, else sniffing); the contentType argument of Put is not persisted.

Symbolic links (rsync -a preserves them) are handled conservatively: a symlink is only followed when it is the last path component and its target is a relative path without ".." segments (so it resolves within the link's own directory subtree); chains are followed up to 8 links. Symlinked directories, absolute targets and targets containing ".." are never followed; such entries are invisible to Get/Stat/List. Directories reached through symlinks are never written to, listed or deleted from.

Writes need rename support, so the fs store cannot write on mountpoint-s3; use the s3 backend there.

The fs store cannot presign URLs; PresignPut and PresignGet return blob.ErrNotSupported (the deploy gateway serves self-hosted upload URLs instead).