github.com/creachadair/ffs@v0.17.3/file/stat.go

// Copyright 2019 Michael J. Fromberger. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package file

import (
	"io/fs"
	"time"

	"github.com/creachadair/ffs/file/wiretype"
)

// A Stat is a view into the stat metadata for a file.
// Modifying fields of the Stat value does not affect the underlying file
// unless the caller explicitly calls Update.
type Stat struct {
	f *File // set for stat views of an existing file; nil OK

	Mode    fs.FileMode `json:"mode,omitempty"`
	ModTime time.Time   `json:"mod_time,omitempty"`

	// Numeric ID and name of file owner.
	OwnerID   int    `json:"owner_id,omitempty"`
	OwnerName string `json:"owner_name,omitempty"`

	// Numeric ID and name of file group.
	GroupID   int    `json:"group_id,omitempty"`
	GroupName string `json:"group_name,omitempty"`

	// To add additional metadata, add a field to this type and a corresponding
	// field to wiretype.Stat, then update the toWireType and fromWireType
	// methods to encode and decode the value.
}

// WithMode returns a copy of s with its Mode set to m.
func (s Stat) WithMode(m fs.FileMode) Stat { s.Mode = m; return s }

// WithModTime returns a copy of s with its ModTime set to ts.
func (s Stat) WithModTime(ts time.Time) Stat { s.ModTime = ts; return s }

// WithOwnerID returns a copy of s with its OwnerID set to id.
func (s Stat) WithOwnerID(id int) Stat { s.OwnerID = id; return s }

// WithOwnerName returns a copy of s with its OwnerName set to name.
func (s Stat) WithOwnerName(name string) Stat { s.OwnerName = name; return s }

// WithGroupID returns a copy of s with its GroupID set to id.
func (s Stat) WithGroupID(id int) Stat { s.GroupID = id; return s }

// WithGroupName returns a copy of s with its GroupName set to name.
func (s Stat) WithGroupName(name string) Stat { s.GroupName = name; return s }

// Clear returns a copy of s with the same file but all other fields set to
// their zero values.
func (s Stat) Clear() Stat { return Stat{f: s.f} }

// Update replaces the stat metadata for the file associated with s with the
// current contents of s. Calling this method does not change whether stat is
// persisted. Update returns s.
func (s Stat) Update() Stat { s.f.mu.Lock(); defer s.f.mu.Unlock(); s.f.setStatLocked(s); return s }

// Persist enables (ok == true) or disables (ok == false) stat persistence for
// the file associated with s. The contents of s are not changed. It returns s.
func (s Stat) Persist(ok bool) Stat {
	s.f.mu.Lock()
	defer s.f.mu.Unlock()
	if ok != s.f.saveStat {
		s.f.saveStat = ok
		s.f.invalLocked()
	}
	return s
}

// Persistent reports whether the file associated with s persists stat.
func (s Stat) Persistent() bool { s.f.mu.RLock(); defer s.f.mu.RUnlock(); return s.f.saveStat }

const (
	bitSetuid = 04000
	bitSetgid = 02000
	bitSticky = 01000
)

// toWireType encodes s as an equivalent wiretype.Stat.
func (s Stat) toWireType() *wiretype.Stat {
	perm := s.Mode.Perm()
	if s.Mode&fs.ModeSetuid != 0 {
		perm |= bitSetuid
	}
	if s.Mode&fs.ModeSetgid != 0 {
		perm |= bitSetgid
	}
	if s.Mode&fs.ModeSticky != 0 {
		perm |= bitSticky
	}
	pb := &wiretype.Stat{
		Permissions: uint32(perm),
		FileType:    modeToType(s.Mode),
	}
	if !s.ModTime.IsZero() {
		pb.ModTime = &wiretype.Timestamp{
			Seconds: uint64(s.ModTime.Unix()),
			Nanos:   uint32(s.ModTime.Nanosecond()),
		}
	}
	if s.OwnerID != 0 || s.OwnerName != "" {
		pb.Owner = &wiretype.Stat_Ident{
			Id:   uint64(s.OwnerID),
			Name: s.OwnerName,
		}
	}
	if s.GroupID != 0 || s.GroupName != "" {
		pb.Group = &wiretype.Stat_Ident{
			Id:   uint64(s.GroupID),
			Name: s.GroupName,
		}
	}
	return pb
}

func modeToType(mode fs.FileMode) wiretype.Stat_FileType {
	switch {
	case mode&fs.ModeType == 0:
		return wiretype.Stat_REGULAR
	case mode&fs.ModeDir != 0:
		return wiretype.Stat_DIRECTORY
	case mode&fs.ModeSymlink != 0:
		return wiretype.Stat_SYMLINK
	case mode&fs.ModeSocket != 0:
		return wiretype.Stat_SOCKET
	case mode&fs.ModeNamedPipe != 0:
		return wiretype.Stat_NAMED_PIPE
	case mode&fs.ModeDevice != 0:
		if mode&fs.ModeCharDevice != 0 {
			return wiretype.Stat_CHAR_DEVICE
		}
		return wiretype.Stat_DEVICE
	default:
		return wiretype.Stat_UNKNOWN
	}
}

var ftypeMode = [...]fs.FileMode{
	wiretype.Stat_REGULAR:     0,
	wiretype.Stat_DIRECTORY:   fs.ModeDir,
	wiretype.Stat_SYMLINK:     fs.ModeSymlink,
	wiretype.Stat_SOCKET:      fs.ModeSocket,
	wiretype.Stat_NAMED_PIPE:  fs.ModeNamedPipe,
	wiretype.Stat_DEVICE:      fs.ModeDevice,
	wiretype.Stat_CHAR_DEVICE: fs.ModeDevice | fs.ModeCharDevice,
}

func typeToMode(ftype wiretype.Stat_FileType) fs.FileMode {
	if n := int(ftype); n >= 0 && n < len(ftypeMode) {
		return ftypeMode[n]
	}
	return fs.ModeIrregular
}

// fromWireType decodes a wiretype.Stat into s. If pb == nil, s is unmodified.
func (s *Stat) fromWireType(pb *wiretype.Stat) {
	if pb == nil {
		return // no stat was persisted for this file
	}
	mode := fs.FileMode(pb.Permissions & 0777)
	if pb.Permissions&bitSetuid != 0 {
		mode |= fs.ModeSetuid
	}
	if pb.Permissions&bitSetgid != 0 {
		mode |= fs.ModeSetgid
	}
	if pb.Permissions&bitSticky != 0 {
		mode |= fs.ModeSticky
	}
	s.Mode = mode | typeToMode(pb.FileType)
	if id := pb.Owner; id != nil {
		s.OwnerID = int(id.Id)
		s.OwnerName = id.Name
	}
	if id := pb.Group; id != nil {
		s.GroupID = int(id.Id)
		s.GroupName = id.Name
	}
	if t := pb.ModTime; t != nil {
		s.ModTime = time.Unix(int64(t.Seconds), int64(t.Nanos))
	}
}