ffi-libfuse 0.3.4 → 0.4.0

data/lib/ffi/libfuse/gem_helper.rb

@@ -5,13 +5,6 @@ module FFI
   module Libfuse
     # @!visibility private
     class GemHelper
-      SEMVER_TAG_REGEX = /^v\d+\.\d+\.\d+/.freeze
-
-      # branches the format is refs/heads/<branch_name>,
-      # tags it is refs/tags/<tag_name>.
-      # for pull requests it is refs/pull/<pr_number>/merge,
-      GIT_REF_TYPES = { 'heads' => :branch, 'tags' => :tag, 'pull' => :pull }.freeze
-
       class << self
         # set when install'd.
         attr_accessor :instance
@@ -33,7 +26,7 @@ module FFI
           return [ref, nil] unless ref&.start_with?('refs/')
 
           _refs, ref_type, ref_name = ref.split('/', 3)
-          [ref_name, GIT_REF_TYPES[ref_type]]
+          [ref_name, { 'heads' => :branch, 'tags' => :tag, 'pull' => :pull }[ref_type]]
         end
 
         def gem_version(main_branch:, version:, env: ENV)
@@ -44,7 +37,7 @@ module FFI
             when :branch
               ref_name == main_branch ? [version] : [version, ref_name]
             when :tag
-              SEMVER_TAG_REGEX.match?(ref_name) ? [ref_name[1..]] : [version, ref_name]
+              /^v\d+\.\d+\.\d+/.match?(ref_name) ? [ref_name[1..]] : [version, ref_name]
             when :pull
               pr_number, merge, _rest = ref_name.split('/')
               # GITHUB_BASE_REF	The name of the base ref or target branch of the pull request in a workflow run

data/lib/ffi/libfuse/io.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    # Helpers for reading/writing to io like objects
+    module IO
+      class << self
+        # Helper to convert a ruby object to size bytes required by {FuseOperations#read}
+        # @param [#pread, #seek & #read, #to_s] io the source to read from, either...
+        #
+        #   * an {::IO} like object via :pread(size, offset) or :seek(offset) then :read(size)
+        #   * or the String from :to_s
+        #
+        # @param [Integer] size
+        # @param [Integer, nil] offset
+        #   if nil the io is assumed to be already positioned
+        # @return [String] the extracted data
+        def read(io, size, offset = nil)
+          return io.pread(size, offset) if offset && io.respond_to?(:pread)
+
+          if (offset ? %i[seek read] : %i[read]).all? { |m| io.respond_to?(m) }
+            io.seek(offset) if offset
+            return io.read(size)
+          end
+
+          io.to_s[offset || 0, size] || ''
+        end
+
+        # Helper to write date to {::IO} or {::String} like objects for use with #{FuseOperations#write}
+        # @param [#pwrite, #seek & #write, #[]=] io an object that accepts String data via...
+        #
+        #   * ```ruby io.pwrite(data, offset)```
+        #   * ```ruby io.seek(offset) ; io.write(data)```
+        #   * ```ruby io[offset, data.size] = data```
+        # @param [String] data
+        # @param [nil, Integer] offset
+        #   if not nil start start writing at this position in io
+        # @return [Integer] number of bytes written
+        # @raise [Errno::EBADF] if io does not support the requisite methods
+        def write(io, data, offset = nil)
+          if offset && io.respond_to?(:pwrite)
+            io.pwrite(data, offset)
+          elsif (offset ? %i[seek write] : %i[write]).all? { |m| io.respond_to?(m) }
+            io.seek(offset) if offset
+            io.write(data)
+          elsif io.respond_to?(:[]=) # eg String
+            io[offset || 0, data.size] = data
+            data.size
+          else
+            raise "cannot :pwrite or :write to #{io}", Errno::EBADF
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/main.rb

@@ -24,15 +24,13 @@ module FFI
 
         # Main function of FUSE
         #
-        # This function:
-        #
         # - parses command line options - see {fuse_parse_cmdline}
-        #   exiting immediately if help or version options were processed
-        # - calls {#fuse_debug}, {#fuse_options}, {#fuse_configure} if implemented by operations
-        # - installs signal handlers for INT, HUP, TERM to unmount and exit filesystem
-        # - installs custom signal handlers if operations implements {fuse_traps}
-        # - creates a fuse handle mounted with registered operations - see {fuse_create}
-        # - calls either the single-threaded (option -s) or the multi-threaded event loop - see {FuseCommon#run}
+        # - calls {#fuse_configure} if implemented by operations
+        # - creates a fuse handle see {fuse_create}
+        # - returns 0 if help or version options were processed (ie after all messages have been printed by libfuse)
+        # - returns 2 if fuse handle is not successfully mounted
+        # - calls {#fuse_traps} if implemented by operations
+        # - calls run on the fuse handle with options from previous steps- see {FuseCommon#run}
         #
         # @param [Array<String>] argv mount.fuse arguments
         #   expects progname, mountpoint, options....
@@ -46,23 +44,23 @@ module FFI
         # @return [Integer] suitable for process exit code
         def fuse_main(*argv, operations:, args: argv.any? ? argv : default_args, private_data: nil)
           run_args = fuse_parse_cmdline(args: args, handler: operations)
-          return 2 unless run_args
 
           fuse_args = run_args.delete(:args)
           mountpoint = run_args.delete(:mountpoint)
 
-          return 3 unless fuse_configure(operations: operations, **run_args)
+          show_only = run_args[:show_help] || run_args[:show_version]
+
+          return 3 if !show_only && !fuse_configure(operations)
 
           warn "FuseCreate: mountpoint: #{mountpoint}, args: [#{fuse_args.argv.join(' ')}]" if run_args[:debug]
           warn "FuseRun: #{run_args}" if run_args[:debug]
 
           fuse = fuse_create(mountpoint, args: fuse_args, operations: operations, private_data: private_data)
 
-          return 0 if run_args[:show_help] || run_args[:show_version]
+          return 0 if show_only
           return 2 if !fuse || !mountpoint
 
-          return unless fuse
-
+          run_args[:traps] = operations.fuse_traps if operations.respond_to?(:fuse_traps)
           fuse.run(**run_args)
         end
         alias main fuse_main
@@ -72,7 +70,6 @@ module FFI
         # - parses standard command line options (-d -s -h -V)
         #   will call {fuse_debug}, {fuse_version}, {fuse_help} if implemented by handler
         # - calls {fuse_options} for custom option processing if implemented by handler
-        # - records signal handlers if operations implements {fuse_traps}
         # - parses standard fuse mount options
         #
         # @param [Array<String>] argv mount.fuse arguments
@@ -88,24 +85,25 @@ module FFI
         #   * show_version [Boolean]: -v or --version
         #   * debug [Boolean]: -d
         #   * others are options to pass to {FuseCommon#run}
+        # @return [nil] if args are not parsed successfully
         def fuse_parse_cmdline(*argv, args: argv.any? ? argv : default_args, handler: nil)
           args = fuse_init_args(args)
 
           # Parse args and print cmdline help
           run_args = Fuse.parse_cmdline(args, handler: handler)
-          return nil unless run_args
 
-          return nil if handler.respond_to?(:fuse_options) && !handler.fuse_options(args)
+          handler.fuse_options(args) if handler.respond_to?(:fuse_options)
 
-          run_args[:traps] = handler.fuse_traps if handler.respond_to?(:fuse_traps)
-
-          return nil unless parse_run_options(args, run_args)
+          parse_run_options(args, run_args)
 
           run_args[:args] = args
           run_args
+        rescue Error
+          nil
         end
 
-        # @return [FuseCommon|nil] the mounted filesystem or nil if not mounted
+        # @return [FuseCommon] the mounted filesystem handle
+        # @return [nil] if not mounted (eg due to --help or --version, or an error)
         def fuse_create(mountpoint, *argv, operations:, args: nil, private_data: nil)
           args = fuse_init_args(args || argv)
 
@@ -116,8 +114,8 @@ module FFI
         end
 
         # @!visibility private
-        def fuse_configure(operations:, show_help: false, show_version: false, **_)
-          return true unless operations.respond_to?(:fuse_configure) && !show_help && !show_version
+        def fuse_configure(operations)
+          return true unless operations.respond_to?(:fuse_configure)
 
           # Provide sensible values for FuseContext in case this is referenced during configure
           FFI::Libfuse::FuseContext.overrides do
@@ -166,7 +164,8 @@ module FFI
       #  @abstract
       #  Called to allow filesystem to handle custom options and observe standard mount options #
       #  @param [FuseArgs] args
-      #  @return [Boolean] true if args parsed successfully
+      #  @raise [Error] if there is an error parsing the options
+      #  @return [void]
       #  @see FuseArgs#parse!
       #  @example
       #    OPTIONS = { 'config=' => :config, '-c ' => :config }
@@ -174,7 +173,7 @@ module FFI
       #       args.parse!(OPTIONS) do |key:, value:, out:, **opts|
       #
       #          # raise errors for invalid config
-      #          raise FFI::Libfuse::FuseArgs::Error, "Invalid config" unless valid_config?(key,value)
+      #          raise FFI::Libfuse::Error, "Invalid config" unless valid_config?(key,value)
       #
       #          # Configure the file system
       #          @config = value if key == :config
@@ -189,6 +188,8 @@ module FFI
 
       # @!method fuse_traps
       #  @abstract
+      #  Passed to {FuseCommon#run} to allow filesystem to handle custom signal traps. These traps
+      #  are merged over those from {FuseCommon#default_traps}
       #  @return [Hash<String|Symbol|Integer,String|Proc>]
       #    map of signal name or number to signal handler as per Signal.trap
       #  @example
@@ -198,6 +199,7 @@ module FFI
 
       # @!method fuse_version
       #  @abstract
+      #  Called as part of generating output for the -V option
       #  @return [String] a custom version string to output with -V option
 
       # @!method fuse_help
@@ -214,6 +216,7 @@ module FFI
       # @!method fuse_configure
       #  @abstract
       #  Called immediately before the filesystem is mounted, after options have been parsed
+      #  (eg to validate required options)
       #
       #  @raise [Error] to prevent the mount from proceeding
       #  @return [void]

data/lib/ffi/libfuse/test_helper.rb

@@ -9,9 +9,6 @@ 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}
@@ -19,7 +16,7 @@ module FFI
       # @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
+      # @yieldparam [String] mnt the temporary directory used as the mount point
       # @raise [Error] if unexpected state is found during operations
       # @return [void]
       def with_fuse(operations, *args, **options)
@@ -34,34 +31,14 @@ module FFI
             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?
+          run_fuse(mnt, *args, operations: operations, **options) do
+            # TODO: Work out why waitpid2 hangs on mac unless the process has already finished
+            sleep 10 if mac_fuse?
 
-          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"
+            _pid, block_status = Process.waitpid2(fpid)
+            block_exit = block_status.exitstatus
+            raise FFI::Libfuse::Error, "forked file operations failed with #{block_exit}" unless block_exit.zero?
           end
-
-          true
         end
       end
 
@@ -77,42 +54,28 @@ module FFI
       # @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
+
+        t, err = safe_fuse do |mnt|
+          t = Thread.new { open3_filesystem(args, env, filesystem, fsname, mnt) }
           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
+            raise Error, "#{fsname} not mounted at #{mnt}" if block_given? && !mounted?(mnt, fsname)
 
-          unmount(mnt) if mounted?(mnt)
-          o, e, s = t.value
-          [o, e, s.exitstatus]
+            yield mnt if block_given?
+            [t, nil]
+          rescue Minitest::Assertion, StandardError => e
+            [t, e]
+          end
         end
+
+        o, e, s = t.value
+        return [o, e, s.exitstatus] unless err
+
+        warn "Errors\n#{e}" unless e.empty?
+        warn "Output\n#{o}" unless o.empty? Minitest::Assertion, StandardError => e
+        raise err
       end
-      # rubocop:enable Metrics/AbcSize
-      # rubocop:enable Metrics/MethodLength
 
       def mounted?(mnt, _filesystem = '.*')
         type, prefix = mac_fuse? ? %w[macfuse /private] : %w[fuse]
@@ -140,6 +103,51 @@ module FFI
       def mac_fuse?
         FFI::Platform::IS_MAC
       end
+
+      private
+
+      def open3_filesystem(args, env, filesystem, fsname, mnt)
+        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
+
+      def run_fuse(mnt, *args, operations:, **options)
+        fuse = mount_fuse(mnt, *args, operations: operations)
+        begin
+          t = Thread.new do
+            Thread.current.name = 'Fuse Run'
+            # Rake owns INT
+            fuse.run(foreground: true, traps: { INT: nil, TERM: nil }, **options)
+          end
+
+          yield
+        ensure
+          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, "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
+        end
+      end
+
+      def mount_fuse(mnt, *args, operations:)
+        operations.fuse_debug(args.include?('-d')) if operations.respond_to?(:fuse_debug)
+
+        fuse = FFI::Libfuse::Main.fuse_create(mnt, *args, operations: operations)
+        raise FFI::Libfuse::Error, 'No fuse object returned from fuse_create' unless fuse
+        raise FFI::Libfuse::Error, 'fuse object is not mounted?' unless fuse.mounted?
+
+        fuse
+      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.3.4'
+    VERSION = '0.4.0'
   end
 end

data/lib/ffi/libfuse.rb

@@ -11,7 +11,7 @@ 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
+    # Filesystems can raise this error to indicate misconfiguration issues etc...
     class Error < StandardError; end
 
     # Opinionated default args for {.main}.

data/lib/ffi/stat/native.rb

@@ -27,14 +27,14 @@ module FFI
                :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
+          native_func = :"native_#{prefix}stat"
+          lib_func = :"#{prefix}stat"
           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
+            native_xfunc = :"native_#{prefix}xstat"
+            lib_xfunc = :"__#{prefix}xstat"
             ::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) }

data/lib/ffi/stat.rb

@@ -62,9 +62,9 @@ module FFI
     # @param [Integer] gid
     # @param [Hash] args additional system specific stat fields
     # @return [self]
-    def file(mode:, size:, uid: Process.uid, gid: Process.gid, **args)
+    def file(mode:, size:, nlink: 1, uid: Process.uid, gid: Process.gid, **args)
       mode = ((S_IFREG & S_IFMT) | (mode & 0o777))
-      fill(mode: mode, size: size, uid: uid, gid: gid, **args)
+      fill(mode: mode, size: size, nlink: nlink, uid: uid, gid: gid, **args)
     end
 
     # Fill content for a directory
@@ -80,6 +80,18 @@ module FFI
     end
     alias directory dir
 
+    # Fill content for a symbolic link
+    # @param [Integer] size length of the target name (including null terminator)
+    # @param [Integer] mode
+    # @param [Integer] uid
+    # @param [Integer] gid
+    # @param [Hash] args additional system specific stat fields
+    # @return [self]
+    def symlink(size:, mode: 0o777, nlink: 1, uid: Process.uid, gid: Process.gid, **args)
+      mode = ((S_IFLNK & S_IFMT) | (mode & 0o777))
+      fill(mode: mode, nlink: nlink, size: size, uid: uid, gid: gid, **args)
+    end
+
     # Fill attributes from file (using native LIBC calls)
     # @param [Integer|:to_s] file descriptor or a file path
     # @param [Boolean] follow links
@@ -123,7 +135,7 @@ module FFI
     # @param [Integer] mask (see umask)
     # @param [Hash] overrides see {fill}
     # @return self
-    def mask(mask = 0o4000, **overrides)
+    def mask(mask = S_ISUID, **overrides)
       fill(mode: mode & (~mask), **overrides)
     end
 
@@ -147,6 +159,10 @@ module FFI
       mode & S_ISVTX != 0
     end
 
+    def symlink?
+      mode & S_IFLNK != 0
+    end
+
     class << self
       # @!method file(stat,**fields)
       # @return [Stat]

data/lib/ffi/struct_array.rb

@@ -10,6 +10,7 @@ module FFI
     def array(size)
       ArrayConverter.new(self, size)
     end
+    alias [] array
 
     # @!visibility private
     # Helper to handle callbacks containing fixed length array of struct
@@ -28,7 +29,7 @@ module FFI
       def from_native(ptr, _ctx)
         return [] if ptr.null?
 
-        Array.new(@size) { |i| @type.new(ptr + (i * @type.size)) }
+        Array.new(@size) { |i| @type.new(ptr + (i * @type.size)) }.freeze
       end
 
       def to_native(ary, _ctx)

data/sample/hello_fs.rb

@@ -51,4 +51,4 @@ class HelloFS
 end
 
 # Start the file system
-FFI::Libfuse.fuse_main(operations: HelloFS.new) if __FILE__ == $0
+exit(FFI::Libfuse.fuse_main(operations: HelloFS.new)) if __FILE__ == $0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffi-libfuse
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Grant Gardner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-08 00:00:00.000000000 Z
+date: 2024-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -161,11 +161,13 @@ files:
 - lib/ffi/libfuse/filesystem/virtual_dir.rb
 - lib/ffi/libfuse/filesystem/virtual_file.rb
 - lib/ffi/libfuse/filesystem/virtual_fs.rb
+- lib/ffi/libfuse/filesystem/virtual_link.rb
 - lib/ffi/libfuse/filesystem/virtual_node.rb
 - lib/ffi/libfuse/fuse2.rb
 - lib/ffi/libfuse/fuse3.rb
 - lib/ffi/libfuse/fuse_args.rb
-- lib/ffi/libfuse/fuse_buffer.rb
+- lib/ffi/libfuse/fuse_buf.rb
+- lib/ffi/libfuse/fuse_buf_vec.rb
 - lib/ffi/libfuse/fuse_callbacks.rb
 - lib/ffi/libfuse/fuse_cmdline_opts.rb
 - lib/ffi/libfuse/fuse_common.rb
@@ -180,6 +182,7 @@ files:
 - lib/ffi/libfuse/fuse_version.rb
 - lib/ffi/libfuse/gem_helper.rb
 - lib/ffi/libfuse/gem_version.rb
+- lib/ffi/libfuse/io.rb
 - lib/ffi/libfuse/job_pool.rb
 - lib/ffi/libfuse/main.rb
 - lib/ffi/libfuse/test_helper.rb