homefs 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7c2589a5398a08b340c286465ef325c6a5cd479d
-  data.tar.gz: e38703f8191b106040c3d24820662264b46543ed
+  metadata.gz: e74057ef8ec81a7efa25cb238fa1d960ec7fa727
+  data.tar.gz: 6a9bff9e3760f6d4f35f5a368849e17d7caecb07
 SHA512:
-  metadata.gz: 1b24049d47a6c5c35bc69305edb6eb9a6b4306b491187beafa492cdfef44f793c11222dc6fb7edb9a517f01a4ac6d3ab2d63baf2cc3767493098770ba6de6115
-  data.tar.gz: 6a75b18765bd4f35f9a464e0b15bf38418814978df1b409d75b15db78280dda08f987f32a43d955ee83c3f9c69bdf713ed58268098c2272b3995321b907512d8
+  metadata.gz: 60a6183228c6436b89a30581a85e47211b9bcf1a56f6fe4e0c50d63b30929c1aa456266be3e2dfde148cec82dbbe062131f57be173d2875c149125e6f83f42cf
+  data.tar.gz: 0a58275485f48cafdc452161d78cdd030b57e9965b22c15608c443db60842386cbdfa4b5d164e0751387cb5f0d0752689af2a634db8e12bff09c34d94603b061

data/lib/homefs/homefs.rb

@@ -1,25 +1,89 @@
 require 'rfusefs'
 
+# An instance of HomeFS; this implements all FuseFS methods, and ultimately
+# handles reading, writing, and inspection of files.
+#
+# We rely on the context provided to us by FUSE to determine the calling user's
+# UID and GID. If you want to access an instance of this class directly, you may
+# set the UID and GID of the current thread like so
+#   Thread.current[:fusefs_reader_uid] = uid
+#   Thread.current[:fusefs_reader_gid] = gid
+# where 'uid' and 'gid' are the desired UID and GID you wish to emulate.
+# @author Dylan Frese
 class HomeFS
+
+    # Creates a new instance of HomeFS. This instance should probably be passed
+    # to FuseFS, as it does nothing on its own. The path is relative to the
+    # calling user's home directory, that is, the user interacting with the
+    # filesystem through open(2), read(2), write(2), etc.
+    # @param [String] path the path, relative to $HOME, to use as the root of
+    # the file system.
     def initialize(path)
         @relpath = path
-        @dirlinks = Hash.new
         read_passwd
+        read_group
     end
 
+    # Read or re-read /etc/passwd to update the internal table of home
+    # directories for each UID. This method does not try to guess as to which
+    # user IDs are owned by actual users of the system, and which are utility
+    # accounts such as 'lp' or 'pulse'.
+    # @return [void]
     def read_passwd
-        # Here we map each line in /etc/passwd to an array,
+        # Try to read from getent
+        passwd = `getent passwd`
+        if $? != 0
+            passwd = File.read('/etc/passwd')
+        end
+
+        @homedirs = Hash.new
+        @usernames = Hash.new
+
+        # Here we map each line in passwd to an array,
         # which Hash interprets as a key, value pair.
-        @homedirs = Hash[
-          File.readlines('/etc/passwd').map do |line|
-              next if line.strip.empty?
-              values = line.split(':')
-              # UID, home directory
-              [Integer(values[2]), values[5]]
-          end
-        ]
+        passwd.each_line.map { |line|
+            next if line.strip.empty?
+            values = line.split(':')
+            # Username, UID, home directory
+            [values[0], Integer(values[2]), values[5]]
+        }.reject { |line|
+            line.nil?
+        }.each { |username, uid, home|
+            @homedirs[uid] = home
+            @usernames[username] = uid
+        }
+    end
+
+    # Read or re-read /etc/group to update the internal table of group
+    # group membership.
+    # @return [void]
+    def read_group
+        # Try to read from getent
+        group = `getent group`
+        if $? != 0
+            group = File.read('/etc/group')
+        end
+
+        @groups = Hash.new
+
+        group.each_line.map { |line|
+            next if line.strip.empty?
+            _name, _, gid, members = line.split(':')
+            members = members.strip.split(',').map {|member| p member; @usernames[member]}
+            [Integer(gid), members]
+        }.reject { |line|
+            line.nil?
+        }.each { |gid, members|
+            @groups[gid] = members
+        }
     end
 
+    # Return the path to the root of HomeFS relative to the underlying
+    # filesystem. If _path_ is specified, it is taken to be relative to the
+    # root of HomeFS.
+    # @return [String] path to the root of the HomeFS relative to the underlying
+    #   filesystem, or if _path_ is specified, the path to that resource
+    #   relative to the underlying filesystem.
     def homepath(path = nil)
         uid = FuseFS.reader_uid
         basepath = @homedirs[uid]
@@ -27,85 +91,184 @@ class HomeFS
         # in case.
         raise Errno::ENOENT if basepath == nil
         if path
-            "#{basepath}/#{@relpath}/#{path}"
+            File.join(basepath, @relpath, path)
         else
-            "#{basepath}/#{@relpath}"
+            File.join(basepath, @relpath)
         end
     end
 
+    # Check whether the given file has a mode that matches the given mask. If
+    # check_ids is true, the third-least significant digit of the mask is set to
+    # zero if the calling user is not the owner of the file, and the
+    # second-least significant digit of the mask is zeroed if the calling user's
+    # group is not the group of the file. This has the effect of only checking
+    # the owner's permissions if we're the owner, and only checking the group
+    # permissions if we're in that group.
+    #
+    # This method checks if _any_ of the set bits in the mask are set in the
+    # file's mode. It does not check if the mask matches the file's mode, nor
+    # does it check if _all_ set bits in the mask are set in the file's mode.
+    #
+    # The first three least significant digits of the mode, in octal, (that is,
+    # the three rightmost digits) control the read (4), write (2), and execute
+    # (1) permissions of the file. The next digit controls setuid (4), setgid
+    # (2), and the sticky bit (1) of the file.
+    #
+    # It is recommended to see
+    #   man chmod
+    # to get a more detailed description about file modes.
+    #
+    # @example Test if we can write to a file
+    #   mode_mask("/example", 0222, true)
+    #   mode_mask("/example", 0222)
+    # @example Test if a file is executable by anyone
+    #   mode_mask("/binary", 0111, false)
+    # @example Test if a directory has the sticky bit set
+    #   mode_mask("/tmp", 01000, false)
+    #
+    # @param [String] file the path to the file to check
+    # @param [Integer] mask the mask against which to check the file's mode.
+    #   It is recommended you write this in octal (with a leading 0).
+    # @param [Boolean] check_ids if true, only check user and group permissions
+    #   if the caller is, respectively, the owner of the file/in the file's
+    #   group.
+    # @return [Boolean] whether the mode of _file_ matches the given mask
     def mode_mask(file, mask, check_ids = true)
         stat = File.stat(file)
-        # First digit: setuid (4), setgid (2), sticky bit (1)
-        # Second, third, and fourth digits: user, group, and
-        # world permissions for read (4), write (2), execute (1)
-        # (see `man chmod` for more)
         fmode = stat.mode
         if check_ids
             fuid, fgid = stat.uid, stat.gid
-            uid, gid = FuseFS.reader_uid, FuseFS.reader_gid
+            uid = FuseFS.reader_uid
             # Zero out the third digit (in octal).
             # We could use a constant here, but this works
             # for a mask of any length
             if uid != fuid
                 mask &= ~(mask & 0700)
             end
-            if gid != fgid
+            if !@groups[fgid].include?(uid)
                 mask &= ~(mask & 0070)
             end
         end
         fmode & mask != 0
     end
 
+    # Test whether we can write to the given path. If no file exists at _path_,
+    # we test if the parent directory is either writable or has the sticky bit
+    # set.
+    # @param [String] path the path to test
+    # @return [Boolean] whether the given path is writable
+    def writable?(path)
+        return true if mode_mask(path, 0222)
+        if !File.exist?(path)
+            mode_mask(File.dirname(path), 01222)
+        else
+            false
+        end
+    end
+
+    # Rename the file or directory at from_path to to_path. This is mostly
+    # equivalent to /bin/mv.
+    # @param [String] from_path the path of the file to be moved
+    # @param [String] to_path the destination of the file
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def rename(from_path, to_path)
         FileUtils.mv(homepath(from_path), homepath(to_path))
     end
 
+    # Update the mtime and atime (last-modified and last-accessed time) of the
+    # file at _path_ to the time given by modtime.
+    # @param [String] path the path to the file to touch
+    # @param [Time] modtime the time to update the file's times to
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def touch(path, modtime)
         File.utime(modtime, modtime, homepath(path))
     end
 
+    # Remove the directory at the given path. The directory must be empty. This
+    # is mostly equivalent to rmdir(1).
+    # @param [String] path the path to the directory to remove
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def rmdir(path)
         FileUtils.rmdir(homepath(path))
     end
 
+    # Test whether we can remove the directory given by _path_.
+    # @param [String] path the path to the directory to test
+    # @return [Boolean] true if the directory given can be removed.
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def can_rmdir?(path)
-        File.writable?(homepath(path))
+        File.writable?(homepath(path)) &&
+            Dir.new(path).to_a.size == 2
     end
 
+    # Make a new directory at _path_. This is similar to mkdir(1).
+    # @param [String] path the path to the directory to make
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def mkdir(path)
         FileUtils.mkdir(homepath(path))
     end
 
+    # Test if we can make a directory at the given path.
+    # @param [String] path the path to test
+    # @return [Boolean] true if we can make a directory at _path_.
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def can_mkdir?(path)
-        writable?(File.dirname(homepath(path)))
+        writable?(homepath(path))
     end
 
+    # Delete the file given by _path_. This is similar to rm(1).
+    # @param [String] path the path to the file to delete
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def delete(path)
         FileUtils.rm(homepath(path))
     end
 
+    # Test if we can delete the file given by _path_.
+    # @param [String] path the path to the file to test
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def can_delete?(path)
         writable?(File.dirname(homepath(path)))
     end
 
+    # Write the given data to the given path.
+    # @param [String] path the path to write to
+    # @param [String] str a binary string of data to write
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def write_to(path, str)
         File.open(homepath(path), "wb") {|file| file.write(str) }
     end
 
-    def writable?(path)
-        mode_mask(path, 0222)
-    end
-
+    # Test whether we can write out to the given path.
+    # @param [String] path the path to test
+    # @return [Boolean] whether we can write to the given path
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def can_write?(path)
-        hpath = homepath(path)
-        if File.exist?(hpath)
-            writable?(hpath)
-        else
-            # FIXME: We don't support sticky bits
-            writable?(File.dirname(hpath))
-        end
+        writable?(homepath(path))
     end
 
+    # Get the times (atime, mtime, ctime) for the file at the given path.
+    # @param [String] path the path to the file to get the times for
+    # @return [Array<Time>] an array of size three of the last-accessed time,
+    #    the last-modified time, and the creation time for the file
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def times(path)
         atime = File.atime(homepath(path))
         mtime = File.mtime(homepath(path))
@@ -113,32 +276,73 @@ class HomeFS
         [atime, mtime, ctime]
     end
 
+    # Test whether the file given by _path_ is executable.
+    # @param [String] path the path to the file to test
+    # @return [Boolean] whether the file at the given path is executable.
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def executable?(path)
         mode_mask(homepath(path), 0111)
     end
 
+    # Read the contents of the file given by _path_.
+    # @param [String] path the path of the file to read
+    # @return [String] a binary string of the contents of the file
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def read_file(path)
         File.open(homepath(path), "rb") do |file|
             file.read
         end
     end
 
+    # List the contents of a directory. This includes '.' and '..' (the current
+    # directory and its parent).
+    # @param [String] path the path to the directory to list
+    # @return [Array<String>] a list of file names of files in the directory
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def contents(path)
         Dir.new(homepath(path)).to_a
     end
 
+    # Get the size of the file at _path_
+    # @param [String] path the path to the file or directory to get the size of
+    # @return [Integer] the size, in bytes, of the file
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def size(path)
         File.size(homepath(path))
     end
 
+    # Test whether _path_ is the name of a file (i.e., not a directory)
+    # @param [String] path the path to test
+    # @return [Boolean] whether _path_ represents a file
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def file?(path)
         File.file?(homepath(path))
     end
 
+    # Test whether _path_ is the name of a directory
+    # @param [String] path the path to test
+    # @return [Boolean] whether _path_ represents a directory
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def directory?(path)
         File.directory?(homepath(path))
     end
 
+    # Open a file handle to the file given by _path_, with the mode given by
+    # _mode_. Right now, the supported modes are "rw", "w", and "r", for
+    # read/write, write, and read. If the mode is write or read/write and no
+    # file exists at _path_, on will be created.
+    # @param [String] path the path to the file to open
+    # @param [String] mode the mode to open the file with
+    # @param rfusefs ignored
+    # @return [File] a file handle of the file given by _path_
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def raw_open(path, mode, rfusefs = nil)
         mode = case mode
                when "rw" then File::RDWR | File::CREAT | File::BINARY
@@ -148,25 +352,67 @@ class HomeFS
         File.open(homepath(path), mode)
     end
 
+    # Read _size_ bytes, starting at _offset_, from the file handle given by _raw_
+    # (which is returned by a call to _raw_open_). If raw is nil and a path is
+    # given, a file will be opened at _path_, and closed after the data is read.
+    # Otherwise, _path_ is ignored.
+    # @param [String] path the path to the file
+    # @param [Integer] offset the offset, in bytes, from the start of the file
+    #   to start reading from.
+    # @param [Integer] size the amount of bytes to read
+    # @param [File] raw the file handle to read from
+    # @return [String] a binary string of the requested data
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def raw_read(path, offset, size, raw = nil)
-        raw ||= raw_open(path, "r")
-        raw.seek(offset, :SET)
-        raw.read(size)
+        file = raw || raw_open(path, "r")
+        file.seek(offset, :SET)
+        file.read(size)
+    ensure
+        file.close if raw.nil?
     end
 
+    # Sync writes to the underlying filesystem. If _raw_ is nil, no operation is
+    # performed.
+    # @param path ignored
+    # @param datasync ignored
+    # @param [File] raw the file handle to sync
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def raw_sync(path, datasync, raw = nil)
         return if raw.nil? # Should we sync anyway?
         raw.fdatasync
     end
 
+    # Close the file handle given by _raw_.
+    # @param path ignored
+    # @param [File] raw the file handle to close
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def raw_close(path, raw = nil)
         return if raw.nil? # ???
         raw.close
     end
 
+    # Write _sz_ bytes from _buf_ to the file handle _raw_, starting at _off_.
+    # If no file handle is given, one will be opened at the given path, and
+    # closed after the write is complete.
+    # @param [String] path the path of the file
+    # @param [Integer] off the offset, in bytes, to starting writing to the
+    #   file at
+    # @param [Integer] sz the amount of bytes to read from buf
+    # @param [String] buf a binary string containing the data to be written
+    # @param [File] raw the file handle to write to
+    # @return [void]
+    # @note This method should usually only be called by FUSE, and not called
+    #   directly
     def raw_write(path, off, sz, buf, raw = nil)
-        raw ||= File.open(path, "w")
-        raw.seek(off, :SET)
-        raw.write(buf[0...sz])
+        file = raw || File.open(path, "w")
+        file.seek(off, :SET)
+        file.write(buf[0...sz])
+    ensure
+        file.close if raw.nil?
     end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: homefs
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Dylan Frese