// Package sourcefs is the write boundary of the skills source. Every write // goes through an *os.Root opened at the source root, so a path that resolves // outside the root through a link is refused by the handle itself. On top of // that, every write first runs Lstat on each component of its path and // refuses when one is a link: os.Root alone still acts on a link that is the // last component, and it allows a relative link that stays inside the root. // // With a sourcewalk.Follow policy, a name below a followed first-level link // (/) is written through a second *os.Root opened at the link's // target, with the same checks on . The link itself is still a link: // it is never written through, removed through, or replaced. // // The package takes plain inputs and must not import internal/config or // internal/sync. package sourcefs import ( "errors" "fmt" "io" "io/fs" "os" "path/filepath" "slices" "strconv" "strings" "time" "skillshare/internal/sourcewalk" "skillshare/internal/utils" ) // ErrLink is matched by every error that refuses a path because one of its // components is a link. var ErrLink = errors.New("path is a link") // ErrLinkedSkillRoot means a skill uninstall would remove its source link. var ErrLinkedSkillRoot = errors.New("linked folder itself; use unlink to remove the link") // LinkError reports the component of a path that is a link. type LinkError struct { Path string // the link, as an absolute path under the source root } func (e *LinkError) Error() string { return fmt.Sprintf("%s is a link; edit its target directly", e.Path) } func (e *LinkError) Is(target error) bool { return target == ErrLink } // Root is an open skills source. Names passed to its methods are relative to // the root and use the OS separator; Rel converts an absolute path. type Root struct { dir string resolved string root *os.Root follow *sourcewalk.Follow linked map[string]*Root // followed link name → root at its target } // Open opens the skills source at dir, which must exist. The root itself may // be a link. An optional follow policy, the one the operation discovered // with, lets writes pass through followed first-level links. func Open(dir string, follow ...*sourcewalk.Follow) (*Root, error) { dir = filepath.Clean(dir) root, err := os.OpenRoot(dir) if err != nil { return nil, err } r := &Root{dir: dir, resolved: utils.ResolveSymlink(dir), root: root} if len(follow) > 0 { r.follow = follow[0] } return r, nil } // Create creates the skills source directory at dir when it is missing, then // opens it. func Create(dir string, follow ...*sourcewalk.Follow) (*Root, error) { if err := os.MkdirAll(dir, 0o755); err != nil { return nil, err } return Open(dir, follow...) } // MkdirAllIn creates name below the source root dir, creating the root when // it is missing. It is for callers that write nothing else. func MkdirAllIn(dir, name string, follow ...*sourcewalk.Follow) error { r, err := Create(dir, follow...) if err != nil { return err } defer r.Close() return r.MkdirAll(name, 0o755) } // CheckMoveOut checks the in-source side of a move of path, below the source // root dir, to a place outside it such as the trash. Such a move cannot use // Root.Rename, so it is checked through the root first: a link above path is // refused. Path itself may be a link; a rename moves the link, never its // target. func CheckMoveOut(dir, path string, follow ...*sourcewalk.Follow) error { return checkMoveOut(dir, path, false, follow...) } // CheckSkillMoveOut also refuses a followed link whose target root is a skill. // Moving that entry would unlink the whole folder instead of removing a skill. // Explicit unlink operations use CheckMoveOut instead. func CheckSkillMoveOut(dir, path string, follow ...*sourcewalk.Follow) error { return checkMoveOut(dir, path, true, follow...) } func checkMoveOut(dir, path string, skill bool, follow ...*sourcewalk.Follow) error { r, err := Open(dir, follow...) if err != nil { return err } defer r.Close() rel, err := r.Rel(path) if err != nil { return err } if skill && !strings.ContainsRune(rel, filepath.Separator) { if _, followed := r.follow.Resolve(path); followed { if _, err := os.Stat(filepath.Join(path, "SKILL.md")); err == nil { return fmt.Errorf("%s is the %w", rel, ErrLinkedSkillRoot) } else if !os.IsNotExist(err) { return err } } } return r.CheckParent(rel) } // Close releases the root and the roots opened at followed link targets. func (r *Root) Close() error { for _, l := range r.linked { l.Close() } return r.root.Close() } // through returns the root at a followed link's target and the rest of name // below the link, when name is / and the policy follows . // Only clean names without ".." qualify; every other name keeps the source // root, which refuses a path through a link. func (r *Root) through(name string) (*Root, string, bool, error) { if r.follow == nil || name != filepath.Clean(name) || filepath.IsAbs(name) { return nil, "", false, nil } parts := strings.Split(name, string(filepath.Separator)) if len(parts) < 2 || slices.Contains(parts, "..") { return nil, "", false, nil } rest := filepath.Join(parts[1:]...) if l, ok := r.linked[parts[0]]; ok { return l, rest, true, nil } target, ok := r.follow.Resolve(filepath.Join(r.dir, parts[0])) if !ok { return nil, "", false, nil } l, err := Open(target) if err != nil { return nil, "", false, err } if r.linked == nil { r.linked = map[string]*Root{} } r.linked[parts[0]] = l return l, rest, true, nil } // Dir returns the source root as it was opened. func (r *Root) Dir() string { return r.dir } // Rel returns the name of the absolute path p relative to the root. p may be // spelled through the root as opened or through its resolved form, which is // what discovery reports when the root is a link. func (r *Root) Rel(p string) (string, error) { p = filepath.Clean(p) for _, base := range []string{r.dir, r.resolved} { rel, err := filepath.Rel(base, p) if err == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) && !filepath.IsAbs(rel) { return rel, nil } } return "", fmt.Errorf("%s is outside the skills source %s", p, r.dir) } // CheckNoLink refuses name when any existing component of it, including the // last, is a link. Components after the first missing one cannot exist, so // the check stops there. func (r *Root) CheckNoLink(name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.CheckNoLink(rest) } return r.checkComponents(name, true) } // CheckParent refuses name when any existing component above the last one is // a link. A move out of the source (trash) uses it: renaming the last // component never follows it, but a link above it would move content that // lives outside the source. func (r *Root) CheckParent(name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.CheckParent(rest) } return r.checkComponents(name, false) } func (r *Root) checkComponents(name string, includeLast bool) error { name = filepath.Clean(name) if name == "." { return nil } parts := strings.Split(name, string(filepath.Separator)) if !includeLast { parts = parts[:len(parts)-1] } prefix := "" for _, part := range parts { prefix = filepath.Join(prefix, part) info, err := r.root.Lstat(prefix) if errors.Is(err, fs.ErrNotExist) { return nil } if err != nil { return err } abs := filepath.Join(r.dir, prefix) if utils.IsLinkMode(abs, info.Mode()) { return &LinkError{Path: abs} } } return nil } // Stat returns the file info of name, following a final link only when it // stays inside the root. func (r *Root) Stat(name string) (fs.FileInfo, error) { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return nil, err } return l.Stat(rest) } return r.root.Stat(name) } // Lstat returns the file info of name without following a final link. func (r *Root) Lstat(name string) (fs.FileInfo, error) { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return nil, err } return l.Lstat(rest) } return r.root.Lstat(name) } // WriteFile writes data to name, creating or truncating it. func (r *Root) WriteFile(name string, data []byte, perm fs.FileMode) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.WriteFile(rest, data, perm) } if err := r.CheckNoLink(name); err != nil { return err } return r.root.WriteFile(name, data, perm) } // OpenFile opens name with the given flags. Any flag that can change the // file runs the link check first. func (r *Root) OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error) { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return nil, err } return l.OpenFile(rest, flag, perm) } if flag&(os.O_WRONLY|os.O_RDWR|os.O_CREATE|os.O_TRUNC|os.O_APPEND) != 0 { if err := r.CheckNoLink(name); err != nil { return nil, err } } return r.root.OpenFile(name, flag, perm) } // MkdirAll creates name and any missing parents. A followed first-level // link already is that directory, so naming one is a no-op. func (r *Root) MkdirAll(name string, perm fs.FileMode) error { if r.follow != nil && name == filepath.Base(name) { if _, ok := r.follow.Resolve(filepath.Join(r.dir, name)); ok { return nil } } if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.MkdirAll(rest, perm) } if err := r.CheckNoLink(name); err != nil { return err } return r.root.MkdirAll(name, perm) } // Remove removes the file or empty directory name. func (r *Root) Remove(name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.Remove(rest) } if err := r.CheckNoLink(name); err != nil { return err } return r.root.Remove(name) } // RemoveAll removes name and everything below it. Links below name are // removed, never followed. func (r *Root) RemoveAll(name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.RemoveAll(rest) } if err := r.CheckNoLink(name); err != nil { return err } return r.root.RemoveAll(name) } // Rename renames oldname to newname, both inside the root, or both below the // same followed link. func (r *Root) Rename(oldname, newname string) error { lo, oldRest, oldOK, err := r.through(oldname) if err != nil { return err } ln, newRest, newOK, err := r.through(newname) if err != nil { return err } if oldOK || newOK { if lo != ln { return fmt.Errorf("cannot rename %s to %s across a followed link", oldname, newname) } return lo.Rename(oldRest, newRest) } if err := r.CheckNoLink(oldname); err != nil { return err } if err := r.CheckNoLink(newname); err != nil { return err } return r.root.Rename(oldname, newname) } // WriteFileAtomic replaces name through a temporary file in the same folder. // The temporary file is created and renamed inside the root, so the first // filesystem change is already constrained by it. func (r *Root) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.WriteFileAtomic(rest, data, perm) } if err := r.CheckNoLink(name); err != nil { return err } temp := filepath.Join(filepath.Dir(name), ".skillshare-"+filepath.Base(name)+"."+strconv.FormatInt(time.Now().UnixNano(), 36)) f, err := r.root.OpenFile(temp, os.O_WRONLY|os.O_CREATE|os.O_EXCL, perm) if err != nil { return fmt.Errorf("create temp: %w", err) } defer func() { _ = r.root.Remove(temp) }() if _, err = f.Write(data); err == nil { err = f.Chmod(perm) } if err == nil { err = f.Sync() } if cerr := f.Close(); err == nil { err = cerr } if err != nil { return fmt.Errorf("write temp: %w", err) } if err := r.root.Rename(temp, name); err != nil { return fmt.Errorf("rename temp: %w", err) } return nil } // MoveIn renames src, which lives outside the root, to name. The move // crosses the root's edge, so it cannot use Root.Rename: the in-source side // is checked through the root first, and name must not exist yet. func (r *Root) MoveIn(src, name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.moveInAnchored(src, rest) } if err := r.CheckNoLink(name); err != nil { return err } if _, err := r.root.Lstat(name); err == nil { return fmt.Errorf("%s already exists", filepath.Join(r.dir, name)) } if _, err := r.root.Stat(filepath.Dir(filepath.Clean(name))); err != nil { return err } return os.Rename(src, filepath.Join(r.dir, name)) } // moveInAnchored is MoveIn for a root opened at a followed link's target. // That target's pathname can be rebound to another directory after the root // was opened, so a pathname rename could land outside the opened checkout. // Instead src is copied through the handle to a temporary name beside name, // renamed into place through the handle, and only then removed. func (r *Root) moveInAnchored(src, name string) error { if err := r.CheckNoLink(name); err != nil { return err } if _, err := r.root.Lstat(name); err == nil { return fmt.Errorf("%s already exists", filepath.Join(r.dir, name)) } temp := filepath.Join(filepath.Dir(name), ".skillshare-"+filepath.Base(name)+"."+strconv.FormatInt(time.Now().UnixNano(), 36)) if err := r.CopyIn(src, temp); err != nil { _ = r.root.RemoveAll(temp) return err } if err := r.root.Rename(temp, name); err != nil { _ = r.root.RemoveAll(temp) return err } return os.RemoveAll(src) } // CopyIn copies the directory tree src, which lives outside the root, to // name. It is the fallback for MoveIn when the rename crosses filesystems // (see IsCrossDevice) and keeps its contract: name must not exist yet, and // every directory and file is created through the root, so a link that // appears at or above name after the check is still refused by the handle. // Links inside src are copied as the content they point at. Dangling links // are skipped; other resolution errors fail the copy. Directory cycles fail. func (r *Root) CopyIn(src, name string) error { if l, rest, ok, err := r.through(name); ok || err != nil { if err != nil { return err } return l.CopyIn(src, rest) } if err := r.CheckNoLink(name); err != nil { return err } if _, err := r.root.Lstat(name); err == nil { return fmt.Errorf("%s already exists", filepath.Join(r.dir, name)) } return r.copyTreeIn(src, name, make(map[string]bool)) } func (r *Root) copyTreeIn(src, name string, active map[string]bool) error { resolved, err := filepath.EvalSymlinks(src) if err != nil { return err } if active[resolved] { return fmt.Errorf("directory link cycle while copying %s", src) } active[resolved] = true defer delete(active, resolved) src = resolved return filepath.Walk(src, func(path string, info fs.FileInfo, err error) error { if err != nil { return err } rel, err := filepath.Rel(src, path) if err != nil { return err } dst := filepath.Join(name, rel) if utils.IsLinkMode(path, info.Mode()) { targetInfo, err := os.Stat(path) if os.IsNotExist(err) { return nil // A dangling staged link has no content to copy. } if err != nil { return err } if targetInfo.IsDir() { return r.copyTreeIn(path, dst, active) } } if info.IsDir() { return r.root.Mkdir(dst, info.Mode().Perm()) } return r.copyFileIn(path, dst) }) } func (r *Root) copyFileIn(src, dst string) error { in, err := os.Open(src) if err != nil { return err } defer in.Close() info, err := in.Stat() if err != nil { return err } out, err := r.root.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_EXCL, info.Mode().Perm()) if err != nil { return err } if _, err := io.Copy(out, in); err != nil { out.Close() return err } return out.Close() } // Unlink removes entry, a first-level link, without touching its target. // It is the only way to remove a link in the source. func (r *Root) Unlink(entry string) error { if entry == "" || entry != filepath.Base(entry) || entry == "." || entry == ".." { return fmt.Errorf("%q is not a first-level entry", entry) } info, err := r.root.Lstat(entry) if err != nil { return err } if !utils.IsLinkMode(filepath.Join(r.dir, entry), info.Mode()) { return fmt.Errorf("%s is not a link", filepath.Join(r.dir, entry)) } return r.root.Remove(entry) }