ffi-libfuse 0.3.4 → 0.4.1

data/lib/ffi/libfuse/fuse_loop_config.rb

@@ -1,43 +1,91 @@
 # frozen_string_literal: true
 
 require_relative '../accessors'
+require_relative '../boolean_int'
 
 module FFI
   module Libfuse
-    # struct fuse_loop_config {
-    #   int clone_fd;
-    #   unsigned int max_idle_threads;
-    # };
+    # For native fuse_loop_mt only
     class FuseLoopConfig < FFI::Struct
       include(FFI::Accessors)
 
-      layout(
-        clone_fd: :int,
-        max_idle: :int
-      )
-
-      # @!attribute [rw] clone_fd
+      # @!attribute [w] clone_fd?
       #   whether to use separate device fds for each thread (may increase performance)
       #   Unused by ffi-libfuse as we do not call fuse_loop_mt
       #   @return [Boolean]
-      ffi_attr_reader(:clone_fd) do |v|
-        v != 0
-      end
-
-      ffi_attr_writer(:clone_fd) do |v|
-        v ? 1 : 0
-      end
 
-      # @!attribute [rw] max_idle_threads
+      # @!attribute [w] max_idle_threads
       #   The maximum number of available worker threads before they start to get deleted when they become idle. If not
       #    specified, the default is 10.
       #
       #   Adjusting this has performance implications; a very small number of threads in the pool will cause a lot of
       #    thread creation and deletion overhead and performance may suffer. When set to 0, a new thread will be created
       #    to service every operation.
-      #
+      #   @deprecated at Fuse 3.12. Use max_threads instead
       #   @return [Integer] the maximum number of threads to leave idle
-      ffi_attr_accessor(:max_idle)
+
+      # @!attribute [w] max_threads
+      #   @return [Integer]
+      #   @since Fuse 3.12
+
+      if FUSE_VERSION >= 312
+        layout(
+          version_id: :int,
+          clone_fd: :bool_int,
+          max_idle_threads: :uint,
+          max_threads: :uint
+        )
+
+        Libfuse.attach_function :fuse_loop_cfg_create, [], by_ref
+        Libfuse.attach_function :fuse_loop_cfg_destroy, [:pointer], :void
+
+        ffi_attr_reader(:clone_fd?)
+        Libfuse.attach_function :fuse_loop_cfg_set_clone_fd, %i[pointer uint], :void
+        def clone_fd=(bool_val)
+          Libfuse.fuse_loop_cfg_set_clone_fd(to_ptr, bool_val ? 1 : 0)
+        end
+
+        ffi_attr_reader(:max_idle_threads)
+        Libfuse.attach_function :fuse_loop_cfg_set_idle_threads, %i[pointer uint], :uint
+        def max_idle_threads=(val)
+          Libfuse.fuse_loop_cfg_set_idle_threads(to_ptr, val) if val
+        end
+
+        Libfuse.attach_function :fuse_loop_cfg_set_max_threads, %i[pointer uint], :uint
+        ffi_attr_reader(:max_threads)
+        def max_threads=(val)
+          Libfuse.fuse_loop_cfg_set_max_threads(to_ptr, val) if val
+        end
+
+        class << self
+          def create(max_idle_threads: nil, max_threads: 10, clone_fd: false, **_)
+            cfg = Libfuse.fuse_loop_cfg_create
+            ObjectSpace.define_finalizer(cfg, finalizer(cfg.to_ptr))
+            cfg.clone_fd = clone_fd
+            cfg.max_idle_threads = max_idle_threads if max_idle_threads
+            cfg.max_threads = max_threads if max_threads
+            cfg
+          end
+
+          def finalizer(ptr)
+            proc { |_| Libfuse.fuse_loop_cfg_destroy(ptr) }
+          end
+        end
+      else
+        layout(
+          clone_fd: :bool_int,
+          max_idle_threads: :uint
+        )
+
+        ffi_attr_accessor(:clone_fd?)
+        ffi_attr_accessor(:max_idle_threads)
+
+        class << self
+          def create(clone_fd: false, max_idle_threads: 10, **_)
+            new.fill(max_idle_threads: max_idle_threads, clone_fd: clone_fd)
+          end
+        end
+      end
     end
   end
 end

data/lib/ffi/libfuse/fuse_operations.rb

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
 require_relative 'fuse_version'
-require_relative '../ruby_object'
 require_relative 'fuse_conn_info'
-require_relative 'fuse_buffer'
+require_relative 'fuse_config'
+require_relative 'fuse_buf_vec'
 require_relative 'fuse_context'
 require_relative 'fuse_file_info'
 require_relative 'fuse_poll_handle'
+require_relative 'fuse_callbacks'
+require_relative '../ruby_object'
 require_relative '../stat_vfs'
 require_relative '../flock'
-require_relative 'thread_pool'
 require_relative '../stat'
-require_relative '../struct_array'
 require_relative '../encoding'
-require_relative 'fuse_callbacks'
 
 module FFI
   # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
@@ -44,18 +43,80 @@ module FFI
     # All Callback methods are optional, but some are essential for a useful filesystem
     # e.g. {getattr},{readdir}
     #
-    # Almost all callback operations take a path which can be of any length and will return 0 for success, or raise a
-    # {::SystemCallError} on failure
+    # Almost all callback operations take a path which can be of any length and will return 0 for success or a negative
+    # `Errno` value on failure.
     #
     class FuseOperations < FFI::Struct
       include FuseCallbacks
 
+      # Callbacks that have no return value
+      VOID_RETURN = %i[init destroy].freeze
+
       # Callbacks that are expected to return meaningful positive integers
       MEANINGFUL_RETURN = %i[read write write_buf lseek copy_file_range getxattr listxattr].freeze
 
-      # @return [Boolean] true if fuse_callback expects a meaningful integer return
-      def self.meaningful_return?(fuse_callback)
-        MEANINGFUL_RETURN.include?(fuse_callback)
+      # @!visibility private
+      # Methods to handle the path argument for most {path_callbacks}
+      NODE_PATH_METHODS = %i[first shift unshift].freeze
+
+      # @!visibility private
+      # Methods to handle the path argument for {link}, {symlink} and {rename}
+      LINK_PATH_METHODS = %i[last pop push].freeze
+
+      # @!visibility private
+      CALLBACK_PATH_ARG_METHODS = Hash.new(NODE_PATH_METHODS).merge(
+        {
+          link: LINK_PATH_METHODS,
+          symlink: LINK_PATH_METHODS,
+          rename: LINK_PATH_METHODS
+        }
+      ).freeze
+
+      class << self
+        # @return [Boolean] true if fuse_callback expects a meaningful integer return
+        def meaningful_return?(fuse_callback)
+          MEANINGFUL_RETURN.include?(fuse_callback)
+        end
+
+        # @return [Boolean] true if fuse_callback expects a void return
+        def void_return?(fuse_callback)
+          VOID_RETURN.include?(fuse_callback)
+        end
+
+        # Helper to determine how to handle the path argument for a path callback
+        # @param [Symbol] fuse_callback callback method name (must be one of #{path_callbacks})
+        # @return [Symbol, Symbol,Symbol] read, remove, add methods.
+        #   [:last, :push, :pop] for :link, :symlink, :rename,
+        #   [:first, :shift, :unshift] for everything else
+        # @example
+        #   def wrap_callback(fuse_method, *args)
+        #       read, remove, add = FFI::Libfuse::FuseOperations.path_arg_methods(fuse_method)
+        #       path = args.send(read)
+        #       # ... do something with path
+        #
+        #       path = args.send(remove)
+        #       # ... do something to make an alternate path
+        #       args.send(add, adjusted_path)
+        #       delegate.send(fuse_methoed, *args)
+        #   end
+        def path_arg_methods(fuse_callback)
+          CALLBACK_PATH_ARG_METHODS[fuse_callback]
+        end
+
+        # @return [Set<Symbol>] list of callback methods
+        def fuse_callbacks
+          @fuse_callbacks ||= Set.new(members - [:flags])
+        end
+
+        # @return [Set<Symbol>] list of path callback methods
+        def path_callbacks
+          @path_callbacks ||= fuse_callbacks - VOID_RETURN
+        end
+      end
+
+      # @!visibility private
+      def fuse_callbacks
+        self.class.fuse_callbacks
       end
 
       # Container to dynamically build up the operations layout which is dependent on the loaded libfuse version
@@ -151,12 +212,11 @@ module FFI
       # int (*rmdir) (const char *);
       op[:rmdir] = []
 
-      # @!method symlink(path,target)
+      # @!method symlink(target, path)
       #  @abstract
       #  Create a symbolic link
+      #  @param [String] target
       #  @param [String] path
-      #  @param [String] target the link target
-      #
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*symlink) (const char *, const char *);
@@ -173,13 +233,13 @@ module FFI
       # int (*rename) (const char *, const char *);
       op[:rename] = [:fs_string]
 
-      # @!method link(path,target)
+      # @!method link(target, path)
       #  @abstract
       #  Create a hard link to a file
-      #  @param [String] path
       #  @param [String] target
-      #
+      #  @param [String] path
       #  @return [Integer] 0 for success or -ve errno
+      #  @see rename(2)
 
       # int (*link) (const char *, const char *);
       op[:link] = [:fs_string]
@@ -486,7 +546,6 @@ module FFI
         # fuse3: void *(*init) (struct fuse_conn_info *conn, struct fuse_config *cfg);
         op[:init] =
           if FUSE_MAJOR_VERSION >= 3
-            require_relative 'fuse_config'
             callback([FuseConnInfo.by_ref, FuseConfig.by_ref], RubyObject)
           else
             callback([FuseConnInfo.by_ref], RubyObject)
@@ -618,7 +677,7 @@ module FFI
         #
 
         # int (*utimens) (const char *, const struct timespec tv[2]);
-        op[:utimens] = [FFI::Stat::TimeSpec.array(2)]
+        op[:utimens] = [FFI::Stat::TimeSpec[2]]
         op[:utimens] << FuseFileInfo.by_ref if FUSE_MAJOR_VERSION >= 3
 
         # @!method bmap(path,blocksize,index)
@@ -655,17 +714,19 @@ module FFI
       #     release, fsync, readdir, releasedir, fsyncdir, ftruncate, fgetattr, lock, ioctl and poll
       #
       #     Closely related to flag_nullpath_ok, but if this flag is set then the path will not be calculaged even if
-      #     the file wasnt unlinked.  However the path can still be non-NULL if it needs to be calculated for some other
-      #     reason.
+      #     the file wasn't unlinked.  However the path can still be non-NULL if it needs to be calculated for some
+      #     other reason.
       #
       #   - :utime_omit_ok
       #
       #     Flag indicating that the filesystem accepts special UTIME_NOW and UTIME_OMIT values in its utimens
       #     operation.
       #
-      #   @return [Array[]Symbol>] a list of flags to set capabilities
+      #   @return [Array<Symbol>] a list of flags to set capabilities
       #   @note Not available in Fuse3
       #   @deprecated in Fuse3 use fuse_config object in {init}
+
+      # flags
       op[:flags] = :flags_mask if FUSE_MAJOR_VERSION < 3
 
       if FUSE_VERSION >= 28
@@ -717,7 +778,7 @@ module FFI
         #  @abstract
         #  Write contents of buffer to an open file
         #
-        #  Similar to the write() method, but data is supplied in a generic buffer.
+        #  Similar to the {write} method, but data is supplied in a generic buffer.
         #  Use {FuseBufVec#copy_to_fd} to copy data to an open file descriptor, or {FuseBufVec#copy_to_str} to extract
         #  string data from the buffer
         #
@@ -734,16 +795,15 @@ module FFI
         # @!method read_buf(path,bufp,size,offset,fuse_file_info)
         #  @abstract
         #
-        #  Similar to the read() method, but data is stored and returned in a generic buffer.
+        #  Similar to the {read} method, but data is stored and returned in a generic buffer.
         #
         #  No actual copying of data has to take place, the source file descriptor may simply be stored in the buffer
         #  for later data transfer.
         #
         #  @param [String] path
         #  @param [FFI::Pointer<FuseBufVec>] bufp
-        #   The buffer must be allocated dynamically and stored at the location pointed to by bufp.  If the buffer
-        #   contains memory regions, they too must be allocated using malloc().  The allocated memory will be freed by
-        #   the caller.
+        #   The buffer must be allocated dynamically ({FuseBufVec.init})
+        #   and stored at the location pointed to by bufp (see {FuseBufVec#store_to}(bufp)).
         #  @param [Integer] size
         #  @param [Integer] offset
         #  @param [FuseFileInfo] fuse_file_info
@@ -886,21 +946,6 @@ module FFI
         fuse_flags.concat(delegate.fuse_flags) if delegate.respond_to?(:fuse_flags)
         send(:[]=, :flags, fuse_flags.uniq)
       end
-
-      # @!visibility private
-      def fuse_callbacks
-        self.class.fuse_callbacks
-      end
-
-      # @return [Set<Symbol>] list of callback methods
-      def self.fuse_callbacks
-        @fuse_callbacks ||= Set.new(members - [:flags])
-      end
-
-      # @return [Set<Symbol>] list of path callback methods
-      def self.path_callbacks
-        @path_callbacks ||= fuse_callbacks - %i[init destroy]
-      end
     end
   end
 end

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,15 +188,22 @@ module FFI
 
       # @!method fuse_traps
       #  @abstract
-      #  @return [Hash<String|Symbol|Integer,String|Proc>]
+      #  Passed to {FuseCommon#run} to allow filesystem to handle custom signal traps. These traps
+      #  are merged over those from {FuseCommon#default_traps}. A nil value can be used to avoid a default trap
+      #  being set.
+      #  @return [Hash<String|Symbol|Integer,String|Proc|nil>]
       #    map of signal name or number to signal handler as per Signal.trap
       #  @example
       #    def fuse_traps
-      #      { HUP: ->() { reload() }}
+      #      {
+      #         HUP: ->() { reload() },
+      #         INT: nil
+      #      }
       #    end
 
       # @!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 +220,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]