ffi-libfuse 0.0.1.rctest12 → 0.3.3

data/lib/ffi/libfuse/test_helper.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative '../libfuse'
+require 'open3'
+require 'sys-filesystem'
+
+# utilities for running tests with fuse filesystems
+module FFI
+  module Libfuse
+    # Can be included test classes to assist with running/debugging filesystems
+    module TestHelper
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/MethodLength
+
+      # Runs the fuse loop on a pre configured fuse filesystem
+      # @param [FuseOperations] operations
+      # @param [Array<String>] args to pass to  {FFI::Libfuse::Main.fuse_create}
+      # @param [Hash] options to pass to {FFI::Libfuse::FuseCommon.run}
+      # @yield [mnt]
+      #   caller can execute and test file operations using mnt and ruby File/Dir etc
+      #   the block is run in a forked process and is successful unless an exception is raised
+      # @yieldparam [String] mnt the temporary direct used as the mount point
+      # @raise [Error] if unexpected state is found during operations
+      # @return [void]
+      def with_fuse(operations, *args, **options)
+        raise ArgumentError, 'Needs block' unless block_given?
+
+        # ignore MacOS special files
+        args << '-onoappledouble,noapplexattr' if mac_fuse?
+        safe_fuse do |mnt|
+          # Start the fork before loading fuse (for MacOS)
+          fpid = Process.fork do
+            sleep 2.5 # Give fuse a chance to start
+            yield mnt
+          end
+
+          fuse = FFI::Libfuse::Main.fuse_create(mnt, *args, operations: operations)
+          raise FFI::Libfuse::Error, 'No fuse object returned from fuse_create' unless fuse
+
+          # Rake owns INT
+          fuse.default_traps.delete(:TERM)
+          fuse.default_traps.delete(:INT)
+
+          raise FFI::Libfuse::Error, 'fuse object is not mounted?' unless fuse.mounted?
+
+          t = Thread.new { fuse.run(foreground: true, **options) }
+
+          # TODO: Work out why waitpid2 hangs on mac unless the process has already finished
+          sleep 10 if mac_fuse?
+
+          _pid, block_status = Process.waitpid2(fpid)
+          block_exit = block_status.exitstatus
+          fuse.exit('fuse_helper')&.join
+          run_result = t.value
+
+          raise FFI::Libfuse::Error, 'fuse is still mounted after fuse.exit' if fuse.mounted?
+          raise FFI::Libfuse::Error, "forked file operations failed with #{block_exit}" unless block_exit.zero?
+          raise FFI::Libfuse::Error, "fuse run failed #{run_result}" unless run_result.zero?
+
+          if !mac_fuse? && mounted?(mnt)
+            raise FFI::Libfuse::Error, "OS reports fuse is still mounted at #{mnt} after fuse.exit"
+          end
+
+          true
+        end
+      end
+
+      # Runs a filesystem in a separate process
+      # @param [String] filesystem path to filesystem executable
+      # @param [Array<String>] args to pass the filesystem
+      # @param [Hash<String,String>] env environment to run the filesystem under
+      # @yield [mnt]
+      #   caller can execute and test file operations using mnt and ruby File/Dir etc
+      # @yieldparam [String] mnt the temporary direct used as the mount point
+      # @raise [Error] if unexpected state is found during operations
+      # @return [Array] stdout, stderr, exit code as captured by Open3.capture3
+      # @note if the filesystem is configured to daemonize then no output will be captured
+      def run_filesystem(filesystem, *args, env: {})
+        fsname = File.basename(filesystem)
+        safe_fuse do |mnt|
+          t = Thread.new do
+            if defined?(Bundler)
+              Bundler.with_unbundled_env do
+                Open3.capture3(env, 'bundle', 'exec', filesystem.to_s, mnt, "-ofsname=#{fsname}", *args, binmode: true)
+              end
+            else
+              Open3.capture3(env, filesystem.to_s, mnt, "-ofsname=#{fsname}", *args, binmode: true)
+            end
+          end
+          sleep 1
+
+          begin
+            if block_given?
+              raise Error, "#{fsname} not mounted at #{mnt}" unless mounted?(mnt, fsname)
+
+              yield mnt
+            end
+            # rubocop:disable Lint/RescueException
+            # Minitest::Assertion and other test assertion classes are not derived from StandardError
+          rescue Exception => _err
+            # rubocop:enable Lint/RescueException
+            unmount(mnt) if mounted?(mnt)
+            o, e, _s = t.value
+            warn "Errors\n#{e}" unless e.empty?
+            warn "Output\n#{o}" unless o.empty?
+            raise
+          end
+
+          unmount(mnt) if mounted?(mnt)
+          o, e, s = t.value
+          [o, e, s.exitstatus]
+        end
+      end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/MethodLength
+
+      def mounted?(mnt, _filesystem = '.*')
+        type, prefix = mac_fuse? ? %w[macfuse /private] : %w[fuse]
+        mounts = Sys::Filesystem.mounts.select { |m| m.mount_type == type }
+        mounts.detect { |m| m.mount_point == "#{prefix}#{mnt}" }
+      end
+
+      def unmount(mnt)
+        if mac_fuse?
+          system("diskutil unmount force #{mnt} >/dev/null 2>&1")
+        else
+          system("fusermount -zu #{mnt} >/dev/null 2>&1")
+        end
+      end
+
+      def safe_fuse
+        Dir.mktmpdir('ffi-libfuse-spec') do |mountpoint|
+          yield mountpoint
+        ensure
+          # Attempt to force unmount.
+          unmount(mountpoint) if mounted?(mountpoint)
+        end
+      end
+
+      def mac_fuse?
+        FFI::Platform::IS_MAC
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/version.rb

@@ -3,6 +3,6 @@
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
   module Libfuse
-    VERSION = '0.0.1'
+    VERSION = '0.3.3'
   end
 end

data/lib/ffi/libfuse.rb

@@ -5,20 +5,29 @@ require_relative 'libfuse/fuse2' if FFI::Libfuse::FUSE_MAJOR_VERSION == 2
 require_relative 'libfuse/fuse3' if FFI::Libfuse::FUSE_MAJOR_VERSION == 3
 require_relative 'libfuse/main'
 require_relative 'libfuse/adapter'
+require_relative 'libfuse/filesystem'
 require_relative 'devt'
 
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
   module Libfuse
+    # Filesystems can raise this error to indicate errors from filesystem users
+    class Error < StandardError; end
+
+    # Opinionated default args for {.main}.
+    #
+    # Filesystems that want full control (eg to take advantage of multi-threaded operations) should call
+    #  {Main.fuse_main} instead
+    # @note These may change between major versions
+    DEFAULT_ARGS = %w[-s -odefault_permissions].freeze
+
     class << self
       # Filesystem entry point
-      # @note This main function defaults to single-threaded operation by injecting the '-s' option. Pass `$0,*ARGV`
-      #   if your filesystem can usefully support multi-threaded operation.
-      #
       # @see Main.fuse_main
-      def fuse_main(*argv, operations:, args: argv.any? ? argv : [$0, '-s', *ARGV], private_data: nil)
+      def fuse_main(*argv, operations:, args: argv.any? ? argv : Main.default_args(*DEFAULT_ARGS), private_data: nil)
         Main.fuse_main(args: args, operations: operations, private_data: private_data) || -1
       end
+      alias main fuse_main
     end
   end
 end

data/lib/ffi/ruby_object.rb

@@ -32,6 +32,7 @@ module FFI
         return nil if object_id.zero?
 
         _ptr, obj = RubyObject.cache[object_id]
+        obj = obj.__getobj__ if obj.is_a?(WeakRef)
         obj
       end
     end
@@ -66,6 +67,8 @@ module FFI
         raise TypeError, "No RubyObject stored at #{ptr.address}" unless cache.key?(ptr.address.object_id)
 
         _ptr, obj = cache[ptr.get(:long, 0)]
+        # unwrap as the object gets used
+        obj = obj.__getobj__ if obj.is_a?(WeakRef)
         obj
       end
 
@@ -74,7 +77,7 @@ module FFI
       end
 
       def finalizer(*keys)
-        proc { keys.each { cache.delete(key) } }
+        proc { keys.each { |k| cache.delete(k) } }
       end
 
       def store(obj)

data/lib/ffi/stat/constants.rb

@@ -25,5 +25,14 @@ module FFI
 
     # Socket
     S_IFSOCK = 0o140000
+
+    # SetUID
+    S_ISUID  = 0o004000
+
+    # SetGID
+    S_ISGID  = 0o002000
+
+    # Sticky Bit
+    S_ISVTX  = 0o001000
   end
 end

data/lib/ffi/stat/native.rb

@@ -5,7 +5,6 @@ require_relative 'time_spec'
 
 module FFI
   class Stat
-    # Native (and naked) stat from stat.h
     # @!visibility private
     class Native < Struct
       case Platform::NAME
@@ -17,31 +16,62 @@ module FFI
                :st_mode,    :mode_t,
                :st_uid,     :uid_t,
                :st_gid,     :gid_t,
-               :__pad0,     :int,
+               :__pad0,     :uint,
                :st_rdev,    :dev_t,
                :st_size,    :off_t,
                :st_blksize, :blksize_t,
                :st_blocks,  :blkcnt_t,
                :st_atimespec, TimeSpec,
                :st_mtimespec, TimeSpec,
-               :st_ctimespec, TimeSpec
+               :st_ctimespec, TimeSpec,
+               :unused, [:long, 3]
+
+        [['', :string], ['l', :string], ['f', :int]].each do |(prefix, ftype)|
+          native_func = "native_#{prefix}stat".to_sym
+          lib_func = "#{prefix}stat".to_sym
+          begin
+            ::FFI::Stat.attach_function native_func, lib_func, [ftype, by_ref], :int
+          rescue FFI::NotFoundError
+            # gLibc 2.31 (Ubuntu focal) does not export these functions, it maps them to __xstat variants
+            native_xfunc = "native_#{prefix}xstat".to_sym
+            lib_xfunc = "__#{prefix}xstat".to_sym
+            ::FFI::Stat.attach_function native_xfunc, lib_xfunc, [:int, ftype, by_ref], :int
+            # 1 is 64 bit versions of struct stat,  3 is 32 bit
+            ::FFI::Stat.define_singleton_method(native_func) { |file, buf| send(native_xfunc, 1, file, buf) }
+          end
+        end
 
-      when 'x65_64-darwin'
+      when 'x86_64-darwin', 'aarch64-darwin'
+        #  man stat - this is stat with 64 bit inodes.
         layout :st_dev,       :dev_t,
-               :st_ino,       :uint32,
                :st_mode,      :mode_t,
                :st_nlink,     :nlink_t,
+               :st_ino,       :ino_t,
                :st_uid,       :uid_t,
                :st_gid,       :gid_t,
                :st_rdev,      :dev_t,
                :st_atimespec, TimeSpec,
                :st_mtimespec, TimeSpec,
                :st_ctimespec, TimeSpec,
+               :st_birthtimespec, TimeSpec,
                :st_size,      :off_t,
                :st_blocks,    :blkcnt_t,
                :st_blksize,   :blksize_t,
                :st_flags,     :uint32,
-               :st_gen,       :uint32
+               :st_gen,       :uint32,
+               :st_lspare,     :int32,
+               :st_gspare,     :int64
+
+        begin
+          # TODO: these functions are deprecated, but at least on Cataline -> Monterey the old stat functions
+          #       use the stat struct *without* 64 bit inodes, but macfuse is compiled with 64 bit inodes
+          ::FFI::Stat.attach_function :native_stat, :stat64, [:string, by_ref], :int
+          ::FFI::Stat.attach_function :native_lstat, :lstat64, [:string, by_ref], :int
+          ::FFI::Stat.attach_function :native_fstat, :fstat64, [:int, by_ref], :int
+        rescue FFI::NotFoundError
+          # these are only used in testing
+        end
+
       else
         raise NotImplementedError, "FFI::Stat not implemented for FFI::Platform #{Platform::NAME}"
       end

data/lib/ffi/stat/time_spec.rb

@@ -14,14 +14,27 @@ module FFI
       # Special nsec value representing a request to omit setting this time - see utimensat(2)
       UTIME_OMIT = (1 << 30) - 2
 
-      # A fixed TimeSpec representing the current time
-      def self.now
-        @now ||= new.set_time(0, UTIME_NOW)
-      end
+      class << self
+        # A fixed TimeSpec representing the current time
+        def now
+          @now ||= new.set_time(0, UTIME_NOW)
+        end
+
+        # A fixed TimeSpec representing a request to omit setting this time
+        def omit
+          @omit ||= new.set_time(0, UTIME_OMIT)
+        end
 
-      # A fixed TimeSpec representing a request to omit setting this time
-      def self.omit
-        @omit ||= new.set_time(0, UTIME_OMIT)
+        # @param [Array<TimeSpec>] times
+        # @param [Integer] size
+        # @return [Array<TimeSpec>] list of times filled out to size with TimeSpec.now if times was empty,
+        #   otherwise with TimeSpec.omit
+        def fill_times(times, size = times.size)
+          return times unless times.size < size
+          return Array.new(size, now) if times.empty?
+
+          times.dup.fill(omit, times.size..size - times.size) if times.size < size
+        end
       end
 
       layout(
@@ -45,15 +58,14 @@ module FFI
 
       # @overload set_time(time)
       #  @param [Time] time
-      #  @return [TimeSpec] self
+      #  @return [self]
       # @overload set_time(sec,nsec=0)
       #  @param [Integer] sec number of (nano/micro)seconds from epoch, precision depending on nsec
       #  @param [Symbol|Integer] nsec
       #   - :nsec to treat sec as number of nanoseconds since epoch
       #   - :usec to treat sec as number of microseconds since epoch
       #   - Integer to treat sec as number of seconds since epoch, and nsec as additional nanoseconds
-      #
-      #  @return [TimeSpec] self
+      #  @return [self]
       def set_time(sec, nsec = 0)
         return set_time(sec.to_i, sec.nsec) if sec.is_a?(Time)
 
@@ -95,6 +107,10 @@ module FFI
         Time.at(sec, nsec, :nsec, in: 0).utc
       end
 
+      def to_s(now = nil)
+        time(now).to_s
+      end
+
       # Convert to Integer
       # @param [Time|nil] now
       #   optional value to use if {now?} is true.  If not set then Time.now will be used

data/lib/ffi/stat.rb

@@ -1,28 +1,19 @@
 # frozen_string_literal: true
 
 require_relative 'struct_wrapper'
-require_relative 'stat/native'
 require_relative 'stat/constants'
 
 module FFI
   # Ruby representation of stat.h struct
   class Stat
-    class << self
-      # @return [Stat] Newly allocated stat representing a regular file - see {Stat#file}
-      def file(**fields)
-        new.file(**fields)
-      end
-
-      # @return [Stat] Newly allocated stat representing a directory - see {Stat#dir}
-      def dir(**fields)
-        new.dir(**fields)
-      end
-      alias directory dir
-    end
-
-    # We need to be a StructWrapper because of clash with #size
+    # Use a StructWrapper because of clash with #size and the ability to attach functions
     include StructWrapper
 
+    extend FFI::Library
+    ffi_lib FFI::Library::LIBC
+
+    # stat/native will attach functions to Stat
+    require_relative 'stat/native'
     native_struct(Native)
 
     # @!attribute [rw] mode
@@ -56,16 +47,12 @@ module FFI
     # @!attribute [rw] ctime
     #   @return [Time] time of last status change
 
-    time_members = Native
-                   .members
-                   .select { |m| m.to_s.start_with?('st_') && m.to_s.end_with?('timespec') }
-                   .map { |m| m[3..-5].to_sym }
+    time_members = Native.members.select { |m| m.to_s =~ /^st_.*timespec$/ }.map { |m| m[3..-5].to_sym }
 
     ffi_attr_reader(*time_members, format: 'st_%sspec', &:time)
 
     ffi_attr_writer(*time_members, format: 'st_%sspec', simple: false) do |sec, nsec = 0|
-      t = self[__method__[0..-2].to_sym]
-      t.set_time(sec, nsec)
+      self[__method__[0..-2].to_sym].set_time(sec, nsec)
     end
 
     # Fill content for a regular file
@@ -87,10 +74,112 @@ module FFI
     # @param [Integer] gid
     # @param [Hash] args additional system specific stat fields
     # @return [self]
-    def dir(mode:, nlink: 1, uid: Process.uid, gid: Process.gid, **args)
+    def dir(mode:, nlink: 3, uid: Process.uid, gid: Process.gid, **args)
       mode = ((S_IFDIR & S_IFMT) | (mode & 0o777))
       fill(mode: mode, uid: uid, gid: gid, nlink: nlink, **args)
     end
     alias directory dir
+
+    # Fill attributes from file (using native LIBC calls)
+    # @param [Integer|:to_s] file descriptor or a file path
+    # @param [Boolean] follow links
+    # @return [self]
+    def from(file, follow: true)
+      return fstat(file) if file.is_a?(Integer)
+
+      return stat(file.to_s) if follow
+
+      lstat(file.to_s)
+    end
+
+    # @!method stat(path)
+    # Fill attributes from file, following links
+    # @param [:to_s] path a file path
+    # @raise [SystemCallError] on error
+    # @return [self]
+
+    # @!method lstat(path)
+    # Fill attributes from file path, without following links
+    # @param [:to_s] path
+    # @raise [SystemCallError] on error
+    # @return [self]
+
+    # @!method fstat(fileno)
+    # Fill attributes from file descriptor
+    # @param [:to_i] fileno file descriptor
+    # @raise [SystemCallError] on error
+    # @return [self]
+
+    %i[stat lstat fstat].each do |m|
+      define_method(m) do |file|
+        res = self.class.send("native_#{m}", (m == :fstat ? file.to_i : file.to_s), native)
+        raise SystemCallError.new('', FFI::LastError.error) unless res.zero?
+
+        self
+      end
+    end
+
+    # Apply permissions mask to mode
+    # @param [Integer] mask (see umask)
+    # @param [Hash] overrides see {fill}
+    # @return self
+    def mask(mask = 0o4000, **overrides)
+      fill(mode: mode & (~mask), **overrides)
+    end
+
+    def file?
+      mode & S_IFREG != 0
+    end
+
+    def directory?
+      mode & S_IFDIR != 0
+    end
+
+    def setuid?
+      mode & S_ISUID != 0
+    end
+
+    def setgid?
+      mode & S_ISGID != 0
+    end
+
+    def sticky?
+      mode & S_ISVTX != 0
+    end
+
+    class << self
+      # @!method file(stat,**fields)
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#file
+
+      # @!method dir(stat,**fields)
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#dir
+      %i[file dir].each { |m| define_method(m) { |stat = new, **args| stat.send(m, **args) } }
+      alias directory dir
+
+      # @!method from(file, stat = new(), follow: false)
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#from
+
+      # @!method stat(file, stat = new())
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#stat
+
+      # @!method lstat(file, stat = new())
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#lstat
+
+      # @!method fstat(file, stat = new())
+      # @return [Stat]
+      # @raise [SystemCallError]
+      # @see Stat#fstat
+      %i[from stat lstat fstat].each { |m| define_method(m) { |file, stat = new, **args| stat.send(m, file, **args) } }
+    end
   end
 end

data/lib/ffi/stat_vfs.rb

@@ -75,7 +75,65 @@ module FFI
     # @!attribute [rw] namemax
     #  @return [Integer] Maximum filename length
 
-    int_members = members.select { |m| m =~ /^f_/ }.map { |m| m[2..].to_sym }
+    int_members = members.grep(/^f_/).map { |m| m[2..].to_sym }
     ffi_attr_accessor(*int_members, format: 'f_%s')
+
+    extend FFI::Library
+    ffi_lib FFI::Library::LIBC
+
+    attach_function :native_statvfs, :statvfs, [:string, by_ref], :int
+    attach_function :native_fstatvfs, :fstatvfs, [:int, by_ref], :int
+
+    # Fill from native statvfs for path
+    # @param [:to_s] path
+    # @return [self]
+    def statvfs(path)
+      res = self.class.native_statvfs(path.to_s, self)
+      raise SystemCallError.new('', FFI::LastError.errno) unless res.zero?
+
+      self
+    end
+
+    # Fill from native fstatvfs for fileno
+    # @param [Integer] fileno
+    # @return [self]
+    def fstatvfs(fileno)
+      res = self.class.native_fstatvfs(fileno, self)
+      raise SystemCallError.new('', FFI::LastError.errno) unless res.zero?
+
+      self
+    end
+
+    # File from native LIBC calls for file
+    # @param [Integer|:to_s] file a file descriptor or a file path
+    # @return [self]
+    def from(file)
+      return fstatvfs(file) if file.is_a?(Integer)
+
+      statvfs(file)
+    end
+
+    class << self
+      # @!method from(file)
+      # @return [StatVfs]
+      # @raise [SystemCallError]
+      # @see StatVfs#from
+
+      # @!method statvfs(file)
+      # @return [StatVfs]
+      # @raise [SystemCallError]
+      # @see StatVfs#statvfs
+
+      # @!method fstatvfs(file)
+      # @return [StatVfs]
+      # @raise [SystemCallError]
+      # @see StatVfs#fstatvfs
+      %i[from statvfs fstatvfs].each { |m| define_method(m) { |file, stat = new, **args| stat.send(m, file, **args) } }
+
+      # @!visibility private
+
+      # @!method native_statvfs(path, statvfs_buf)
+      # @!method native_fstatvfs(fd, statvfs_buf)
+    end
   end
 end

data/lib/ffi/struct_wrapper.rb

@@ -5,6 +5,16 @@ require_relative 'accessors'
 
 module FFI
   # Helper to wrap structs with ugly names and attribute clashes with FFI::Struct (eg size)
+  #
+  # @example
+  #  class MyStruct
+  #    include FFI::StructWrapper
+  #    native_struct(MyNativeStruct)
+  #
+  #    #!@attribute [rw] field
+  #    ffi_attr_accessor :field
+  #  end
+  #
   module StructWrapper
     # @!visibility private
     class ByReference < StructByReference
@@ -78,8 +88,9 @@ module FFI
 
     # @!parse extend ClassMethods
     # @!parse include Accessors
+    # @!parse extend Accessors::ClassMethods
 
-    # @!visibility private
+    # @return [FFI::Struct] the underlying native struct
     attr_reader :native
 
     # @!visibility private
@@ -96,5 +107,15 @@ module FFI
     def []=(member_or_attr, val)
       @native[self.class.ffi_attr_writers.fetch(member_or_attr, member_or_attr)] = val
     end
+
+    # Pass unimplemented methods on to {#native} underlying struct
+    def method_missing(method, *args)
+      @native.send(method, *args)
+    end
+
+    # @!visibility private
+    def respond_to_missing?(method, private = false)
+      @native.respond_to?(method, private)
+    end
   end
 end