Documentation
¶
Index ¶
- func Copy(ctx context.Context, srcFs, dstFs fs.FS) error
- func MkdirAll(afs fs.FS, path fs.RelPath, perms fs.Perms) error
- func MkdirUsable(afs fs.FS, path fs.RelPath, preferredProps fs.Metadata) error
- func PlaceFile(afs fs.FS, fmeta fs.Metadata, body io.Reader, skipChown bool) error
- func RemoveDirContent(afs fs.FS, path fs.RelPath) error
- func RepairMtime(afs fs.FS, path fs.RelPath) func()
- func ScanFile(afs fs.FS, path fs.RelPath) (fmeta *fs.Metadata, body io.ReadCloser, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Copy ¶
Copy does a recursive copy from src to dst; it correctly handles most files (e.g. symlinks, etc), but is fairly sloppy with attributes (does not chown the dst, nor attempt to maintain timestamps).
Copy is here as a convenient library function if you need it, but note that it's a lot less precise than a pair of "rio pack | rio unpack" commands, and also this method does not hash.
func MkdirAll ¶
Makes dirs recursively so the requested path exists, applying the assigned metadata to each one that needed to be produced.
Existing dirs are not mutated.
Symlinks will be traversed without comment (i.e. this will never emit ErrBreakout). (Note that this means this function is *not* used in either transmats nor stitch.)
func MkdirUsable ¶
A form of MkdirAll, recursively creating parent directories as necessary, but with more behaviors: the final directory will have all its metadata and permissions forced to the given uid+gid and its permissions bitwise `|0700` (owner rw), and all parents bitwise `|0001` (everyone-traversable), and all affected dirs and their parents will have their mtimes repaired.
The preferredProps metadata is only partially followed, as the rules above take precidence; but the preferredProps will be used for any dirs that need be created.
If intermediate path segements are not dirs, errors will be returned.
Long story short, it makes sure the given path is read-write *usable* to the given uid+gid. (Repeatr leans on this in the "cradle" functionality.)
func PlaceFile ¶
Places a file on the filesystem. Replicates all attributes described in the metadata.
The path within the filesystem is `hdr.Name` (conventionally, this means the filesystem will join the `hdr.Name` with the absolute base path it was constructed with).
No changes are allowed to occur outside of the filesystem's base path. Hardlinks may not point outside of the base path. Symlinks may *point* at paths outside of the base path (because you may be about to chroot into this, in which case absolute link paths make perfect sense), and invalid symlinks are acceptable -- however symlinks may *not* be traversed during any part of `hdr.Name`; this is considered malformed input and will result in a BreakoutError.
Please note that like all filesystem operations within a lightyear of symlinks, all validations are best-effort, but are only capable of correctness in the absense of concurrent modifications inside `destBasePath`.
Device files *will* be created, with their maj/min numbers. This may be considered a security concern; you should whitelist inputs if using this to provision a sandbox.
When the metadata describes a directory, and the existing data on the filesystem is also a directory, the attributes will be assigned without comment. For all other types (files, symlinks, device nodes, etc), using PlaceFile will error if there is existing data.
If skipChown is true, it does what it says on the tin: skips setting ownership. This will result in UIDs and GIDs from the rio process being in effect; it's also a rough proxy for "don't require priviledged operations". PlaceFile will also automatically skip any chown syscalls if it detects that the current process is running with the same numeric uid and gid specified in the the fs.Metadata struct, so you can almost always call Placefile with skipChown=false unless you're doing something special. (Ecosystemically: don't combine skipChown=true with content-addressable storage; the result will be collision errors and incorrect behavior. Similarly, Repeatr would *never* use the skipChown option, because it would create consistency issues. But `rio unpack` is happy to do so, because it is not the unpack command's job to maintain a CAS filesystem.)
func RemoveDirContent ¶
Remove all files and dirs in a dir (if it exists; if not, no-op), recursing as necessary.
This can be useful to do before e.g. some 'unpack' operation, to make sure no content collides, while also avoiding unlinking the top level dir, in case the current process would lack permission to create it again.
As an additional edge case, if the given path is a file and not a dir, the file will also be removed (so, the consistent logic here is you will be ready to have a dir in this path (aka, target an unpack here) when this function returns).
func RepairMtime ¶
Records the mtime property currently set on a path and returns a function which will force it to that value again.
The typical use for this is `defer RepairMtime(fs, "./somedir")()` right before invoking some funcs which will mutate the contents of that dir. When the rest of the changes are done and the function returns, the mtime of the dir will be forced back to its previous value, seemingly unchanged.
Types ¶
This section is empty.
Source Files