ffi-libfuse 0.0.1.rctest12 → 0.3.3

data/lib/ffi/libfuse/fuse_operations.rb

@@ -12,28 +12,36 @@ 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)
   module Libfuse
+    # All paths are encoded in ruby's view of the filesystem encoding
+    typedef Encoding.for('filesystem'), :fs_string
+
     # typedef int (*fuse_fill_dir_t) (void *buf, const char *name, const struct stat *stbuf, off_t off);
-    fill_dir_t_args = [:pointer, :string, Stat.by_ref, :off_t]
+    fill_dir_t_args = [:pointer, :fs_string, Stat.by_ref, :off_t]
     if FUSE_MAJOR_VERSION > 2
       enum :fuse_readdir_flags, [:fuse_readdir_plus, (1 << 0)]
       enum :fuse_fill_dir_flags, [:fuse_fill_dir_plus, (1 << 1)]
       fill_dir_t_args << :fuse_fill_dir_flags
     end
 
+    bitmask :fuse_ioctl_flags, %i[compat unrestricted retry dir]
     bitmask :lock_op, [:lock_sh, 0, :lock_ex, 2, :lock_nb, 4, :lock_un, 8]
     bitmask :falloc_mode, %i[keep_size punch_hole no_hide_stale collapse_range zero_range insert_range unshare_range]
     bitmask :flags_mask, %i[nullpath_ok nopath utime_omit_ok] if FUSE_MAJOR_VERSION < 3
-    enum :xattr, [:xattr_create, 1, :xattr_replace]
+
+    # @!visibility private
+    XAttr = enum :xattr, [:xattr_create, 1, :xattr_replace]
+
     callback :fill_dir_t, fill_dir_t_args, :int
 
     # The file system operations as specified in libfuse.
     #
-    # All Callback and Configuration methods are optional, but some are essential for a useful filesystem
+    # 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
@@ -42,6 +50,14 @@ module FFI
     class FuseOperations < FFI::Struct
       include FuseCallbacks
 
+      # 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)
+      end
+
       # Container to dynamically build up the operations layout which is dependent on the loaded libfuse version
       op = {}
 
@@ -144,7 +160,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*symlink) (const char *, const char *);
-      op[:symlink] = [:string]
+      op[:symlink] = [:fs_string]
 
       # @!method rename(from_path,to_path)
       #  @abstract
@@ -155,7 +171,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*rename) (const char *, const char *);
-      op[:rename] = [:string]
+      op[:rename] = [:fs_string]
 
       # @!method link(path,target)
       #  @abstract
@@ -166,7 +182,7 @@ module FFI
       #  @return [Integer] 0 for success or -ve errno
 
       # int (*link) (const char *, const char *);
-      op[:link] = [:string]
+      op[:link] = [:fs_string]
 
       # @!method chmod(path,mode,fuse_file_info=nil)
       #  @abstract
@@ -208,6 +224,7 @@ module FFI
       op[:truncate] = [:off_t]
       op[:truncate] << FuseFileInfo.by_ref if FUSE_MAJOR_VERSION >= 3
 
+      # Not directly implemented see utimens
       # int (*utime) (const char *, struct utimbuf *);
       op[:utime] = [:pointer] if FUSE_MAJOR_VERSION < 3
 
@@ -563,7 +580,7 @@ module FFI
         #  @param [String] path
         #  @param [FuseFileInfo] fuse_file_info
         #    For checking lock ownership, the 'fuse_file_info->owner' argument must be used.
-        #  @param [Symbol] cmd either :f_getlck, :f_setlck or :f_setlkw.
+        #  @param [Symbol] cmd either :getlck, :setlck or :setlkw.
         #  @param [Flock] flock
         #    For the meaning of fields in 'struct flock' see the man page for fcntl(2).  The whence field will always
         #    be set to :seek_set.
@@ -660,18 +677,21 @@ module FFI
         #  @param [Integer] cmd
         #  @param [FFI::Pointer] arg
         #  @param [FuseFileInfo] fuse_file_info
-        #  @param [Integer] flags
-        #  @param [FFI::Pointer] data
+        #  @param [Array<Symbol>] flags
         #
-        #  flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in 64bit environment.  The size and direction of data
-        #  is determined by _IOC_*() decoding of cmd.  For _IOC_NONE, data will be NULL, for _IOC_WRITE data is out
-        #  area, for _IOC_READ in area and if both are set in/out area.  In all non-NULL cases, the area is of
-        #  _IOC_SIZE(cmd) bytes.
+        #    - :compat       32bit compat ioctl on 64bit machine
+        #    - :unrestricted not restricted to well-formed ioctls, retry allowed (lowlevel fuse)
+        #    - :retry        retry with new iovecs (lowlevel fuse)
+        #    - :dir          is a directory file handle
         #
-        #  If flags has FUSE_IOCTL_DIR then the fuse_file_info refers to a directory file handle.
+        #  @param [FFI::Pointer] data
+        #
+        #  The size and direction of data is determined by _IOC_*() decoding of cmd.  For _IOC_NONE, data will be NULL,
+        #  for _IOC_WRITE data is out area, for _IOC_READ in area and if both are set in/out area.  In all non-NULL
+        #  cases, the area is of _IOC_SIZE(cmd) bytes.
 
         # int (*ioctl) (const char *, int cmd, void *arg, struct fuse_file_info *, unsigned int flags, void *data);
-        op[:ioctl] = [:int, :pointer, FuseFileInfo.by_ref, :uint, :pointer]
+        op[:ioctl] = [:int, :pointer, FuseFileInfo.by_ref, :fuse_ioctl_flags, :pointer]
 
         # @!method poll(path,fuse_file_info,ph,reventsp)
         #  @abstract
@@ -697,8 +717,9 @@ module FFI
         #  @abstract
         #  Write contents of buffer to an open file
         #
-        #  Similar to the write() method, but data is supplied in a generic buffer.  Use fuse_buf_copy() to transfer
-        #  data to the destination.
+        #  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
         #
         #  @param [String] path
         #  @param [FuseBufVec] buf
@@ -804,8 +825,8 @@ module FFI
           # );
           op[:copy_file_range] =
             callback [
-              :string, FuseFileInfo.by_ref, :off_t,
-              :string, FuseFileInfo.by_ref, :off_t,
+              :fs_string, FuseFileInfo.by_ref, :off_t,
+              :fs_string, FuseFileInfo.by_ref, :off_t,
               :size_t, :int
             ], :ssize_t
 
@@ -820,7 +841,7 @@ module FFI
           #  @see lseek(2)
 
           # off_t (*lseek) (const char *, off_t off, int whence, struct fuse_file_info *);
-          op[:lseek] = callback [:string, :off_t, Flock::Enums::SeekWhence, FuseFileInfo.by_ref], :off_t
+          op[:lseek] = callback [:fs_string, :off_t, Flock::Enums::SeekWhence, FuseFileInfo.by_ref], :off_t
         end
       end
 
@@ -829,7 +850,7 @@ module FFI
       layout_data = op.transform_values do |v|
         if v.is_a?(Array) && !v.last.is_a?(Integer)
           # A typical fuse callback
-          callback([:string] + v, :int)
+          callback([:fs_string] + v, :int)
         else
           v
         end
@@ -865,6 +886,21 @@ 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/fuse_opt.rb

@@ -19,7 +19,7 @@ module FFI
       def fill(template, value)
         str_ptr = FFI::MemoryPointer.from_string(template)
         self[:template] = str_ptr
-        self[:offset] = (2**(8 * FFI::Type::INT.size)) - 1 # -(1U)  in a LONG!!
+        self[:offset] = (2**(FFI::Type::INT.size * 8)) - 1 # -(1U)  in a LONG!!
         self[:value] = value.to_i
         self
       end

data/lib/ffi/libfuse/fuse_version.rb

@@ -9,15 +9,18 @@ module FFI
   module Libfuse
     extend FFI::Library
 
+    libs =
+      case FFI::Platform::NAME
+      when 'x86_64-darwin'
+        %w[libfuse.2.dylib]
+      else
+        %w[libfuse3.so.3 libfuse.so.2]
+      end
     # The fuse library to load from 'LIBFUSE' environment variable if set, otherwise prefer Fuse3 over Fuse2
-    LIBFUSE = ENV['LIBFUSE'] || %w[libfuse3.so.3 libfuse.so.2]
+    LIBFUSE = ENV.fetch('LIBFUSE', libs)
     ffi_lib(LIBFUSE)
 
-    # @!scope class
-    # @!method fuse_version()
-    # @return [Integer] the fuse version
-    # See {FUSE_VERSION} which captures this result in a constant
-
+    # @!visibility private
     attach_function :fuse_version, [], :int
 
     # prior to 3.10 this is Major * 10 + Minor, after 3.10 and later is Major * 100 + Minor
@@ -36,6 +39,7 @@ module FFI
       require_relative '../gnu_extensions'
 
       extend(GNUExtensions)
+
       # libfuse2 has busted symbols
       ffi_lib_versions(%w[FUSE_2.9.1 FUSE_2.9 FUSE_2.8 FUSE_2.7 FUSE_2.6 FUSE_2.5 FUSE_2.4 FUSE_2.3 FUSE_2.2])
     end

data/lib/ffi/libfuse/gem_version.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    # @!visibility private
+
+    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
+
+    def self.git_ref(env: ENV)
+      ref = env.fetch('GIT_REF') do
+        # get branch ref, or detached head ref to tag
+        `git symbolic-ref HEAD 2>/dev/null || git name-rev HEAD | awk '{ gsub(/[\\^~@].*$/,"",$2); printf("refs/%s\\n",$2)}'`.strip # rubocop:disable Layout/LineLength
+      rescue StandardError
+        nil
+      end
+
+      return [ref, nil] unless ref&.start_with?('refs/')
+
+      _refs, ref_type, ref_name = ref.split('/', 3)
+      [ref_name, GIT_REF_TYPES[ref_type]]
+    end
+
+    def self.gem_version(main_branch: 'main', version: VERSION, env: ENV)
+      ref_name, ref_type = git_ref(env: env)
+
+      version =
+        case ref_type
+        when :branch
+          ref_name == main_branch ? [version] : [version, ref_name]
+        when :tag
+          SEMVER_TAG_REGEX.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
+          base_ref = env.fetch('GIT_BASE_REF', 'undefined')
+          [version, base_ref, "#{merge}#{pr_number}"]
+        else
+          [version, 'pre', ref_name]
+        end.select { |p| p && !p.empty? }.join('.').tr('//_-', '')
+
+      [version, ref_name, ref_type]
+    end
+
+    GEM_VERSION, GIT_REF_NAME, GIT_REF_TYPE = gem_version
+  end
+end

data/lib/ffi/libfuse/main.rb

@@ -9,12 +9,26 @@ module FFI
     # Controls the main run loop for a FUSE filesystem
     module Main
       class << self
+        # Builds default argument list for #{fuse_main} regardless of being called directly or from mount.fuse3
+        #
+        # @param [Array<String>] extra_args additional arguments to add to $0 and *ARGV
+        # @return [Array<String>]
+        # @see https://github.com/libfuse/libfuse/issues/621
+        def default_args(*extra_args)
+          args = ARGV.dup
+
+          # If called from mount.fuse3 we already have a 'source' argument which should go at args[0]
+          args.unshift($0) unless args.size >= 2 && args[0..1].all? { |a| !a.start_with?('-') }
+          args.concat(extra_args)
+        end
+
         # Main function of FUSE
         #
         # This function:
         #
         # - parses command line options - see {fuse_parse_cmdline}
-        #   and exits immediately if help or version options were processed
+        #   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}
@@ -22,7 +36,7 @@ module FFI
         #
         # @param [Array<String>] argv mount.fuse arguments
         #   expects progname, mountpoint, options....
-        # @param [FuseArgs] args
+        # @param [FuseArgs|Array<String>] args
         #   alternatively constructed args
         # @param [Object|FuseOperations] operations
         #  something that responds to the fuse callbacks and optionally our abstract configuration methods
@@ -30,13 +44,18 @@ module FFI
         #  any data to be made available to the {FuseOperations#init} callback
         #
         # @return [Integer] suitable for process exit code
-        def fuse_main(*argv, operations:, args: argv, private_data: nil)
+        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)
+
+          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]
@@ -44,52 +63,43 @@ module FFI
 
           return unless fuse
 
-          warn run_args.to_s if run_args[:debug]
-
           fuse.run(**run_args)
         end
+        alias main fuse_main
 
         # Parse command line arguments
         #
         # - parses standard command line options (-d -s -h -V)
         #   will call {fuse_debug}, {fuse_version}, {fuse_help} if implemented by handler
-        # - parses custom options if handler implements {fuse_options} and {fuse_opt_proc}
+        # - 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
-        #   expects progname, [fsname,] mountpoint, options.... from mount.fuse3
+        #   expects progname, mountpoint, options....
         # @param [FuseArgs] args
         #   alternatively constructed args
         # @param [Object] handler
         #   something that responds to our abstract configuration methods
-        # @param [Object] private_data passed to handler.fuse_opt_proc
-        #
         # @return [Hash<Symbol,Object>]
-        #   * fsname [String]: the fsspec from /etc/fstab
         #   * mountpoint [String]: the mountpoint argument
         #   * args [FuseArgs]: remaining fuse_args to pass to {fuse_create}
         #   * show_help [Boolean]: -h or --help
         #   * show_version [Boolean]: -v or --version
         #   * debug [Boolean]: -d
         #   * others are options to pass to {FuseCommon#run}
-        def fuse_parse_cmdline(*argv, args: argv, handler: nil, private_data: nil)
+        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
 
-          # process custom options
-          if %i[fuse_options fuse_opt_proc].all? { |m| handler.respond_to?(m) }
-            parse_ok = args.parse!(handler.fuse_options, private_data) do |*p_args|
-              handler.fuse_opt_proc(*p_args)
-            end
-            return unless parse_ok
-          end
+          return nil if handler.respond_to?(:fuse_options) && !handler.fuse_options(args)
 
           run_args[:traps] = handler.fuse_traps if handler.respond_to?(:fuse_traps)
 
-          args.parse!(RUN_OPTIONS, run_args) { |*opt_args| hash_opt_proc(*opt_args, discard: %i[native max_threads]) }
+          return nil unless parse_run_options(args, run_args)
 
           run_args[:args] = args
           run_args
@@ -97,40 +107,41 @@ module FFI
 
         # @return [FuseCommon|nil] the mounted filesystem or nil if not mounted
         def fuse_create(mountpoint, *argv, operations:, args: nil, private_data: nil)
-          args = fuse_init_args(args || argv.unshift(mountpoint))
+          args = fuse_init_args(args || argv)
 
           operations = FuseOperations.new(delegate: operations) unless operations.is_a?(FuseOperations)
 
-          fuse = Fuse.new(mountpoint, args, operations, private_data)
+          fuse = Fuse.new(mountpoint.to_s, args, operations, private_data)
           fuse if fuse.mounted?
         end
 
-        # Helper fuse_opt_proc function to capture options into a hash
-        #
-        # See {FuseArgs.parse!}
-        def hash_opt_proc(hash, arg, key, _out, discard: [])
-          return :keep if %i[unmatched non_option].include?(key)
-
-          hash[key] = arg =~ /=/ ? arg.split('=', 2).last : true
-          discard.include?(key) ? :discard : :keep
+        # @!visibility private
+        def fuse_configure(operations:, show_help: false, show_version: false, **_)
+          return true unless operations.respond_to?(:fuse_configure) && !show_help && !show_version
+
+          # Provide sensible values for FuseContext in case this is referenced during configure
+          FFI::Libfuse::FuseContext.overrides do
+            operations.fuse_configure
+            true
+          rescue Error => e
+            warn e.message
+            false
+          rescue StandardError, ScriptError => e
+            warn "#{e.class.name}: #{e.message}\n\t#{e.backtrace.join("\n\t")}"
+            false
+          end
         end
 
         # @!visibility private
-
-        # Version text
         def version
           "#{name}: #{VERSION}"
         end
 
+        private
+
         def fuse_init_args(args)
           if args.is_a?(Array)
-            args = args.map(&:to_s) # handle mountpoint as Pathname etc..
-
-            # https://github.com/libfuse/libfuse/issues/621 handle "source" field sent from /etc/fstab via mount.fuse3
-            # if arg[1] and arg[2] are both non option fields then replace arg1 with -ofsname=<arg1>
-            unless args.size <= 2 || args[1]&.start_with?('-') || args[2]&.start_with?('-')
-              args[1] = "-ofsname=#{args[1]}"
-            end
+            warn "FuseArgs: #{args.join(' ')}" if args.include?('-d')
             args = FuseArgs.create(*args)
           end
 
@@ -138,23 +149,52 @@ module FFI
 
           raise ArgumentError "fuse main args: must be Array<String> or #{FuseArgs.class.name}"
         end
+
+        def parse_run_options(args, run_args)
+          args.parse!(RUN_OPTIONS) do |key:, value:, **|
+            run_args[key] = value
+            next :keep if (STANDARD_OPTIONS.values + %i[remember]).include?(key)
+
+            :discard
+          end
+        end
       end
 
       # @!group Abstract Configuration
 
-      # @!method fuse_options
+      # @!method fuse_options(args)
       #  @abstract
-      #  @return [Hash] custom option schema
-      #  @see FuseArgs#parse!
-
-      # @!method fuse_opt_proc(data,arg,key,out)
-      #  @abstract
-      #  Process custom options
+      #  Called to allow filesystem to handle custom options and observe standard mount options #
+      #  @param [FuseArgs] args
+      #  @return [Boolean] true if args parsed successfully
       #  @see FuseArgs#parse!
+      #  @example
+      #    OPTIONS = { 'config=' => :config, '-c ' => :config }
+      #    def fuse_options(args)
+      #       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)
+      #
+      #          # Configure the file system
+      #          @config = value if key == :config
+      #
+      #          #Optionally manipulate other arguments for fuse_mount() based on the current argument and state
+      #          out.add('-oopt=val')
+      #
+      #          # Custom options must be marked :handled otherwise fuse_mount() will fail with unknown arguments
+      #          :handled
+      #       end
+      #    end
 
       # @!method fuse_traps
       #  @abstract
-      #  @return [Hash] map of signal name or number to signal handler as per Signal.trap
+      #  @return [Hash<String|Symbol|Integer,String|Proc>]
+      #    map of signal name or number to signal handler as per Signal.trap
+      #  @example
+      #    def fuse_traps
+      #      { HUP: ->() { reload() }}
+      #    end
 
       # @!method fuse_version
       #  @abstract
@@ -162,14 +202,22 @@ module FFI
 
       # @!method fuse_help
       #  @abstract
-      #  @return [String] help text to explain custom options to show with -h option
+      #  Called as part of generating output for the -h option
+      #  @return [String] help text to explain custom options
 
       # @!method fuse_debug(enabled)
       #  @abstract
-      #  Indicate to the filesystem whether debugging option is in use.
+      #  Called to indicate to the filesystem whether debugging option is in use.
       #  @param [Boolean] enabled if -d option is in use
       #  @return [void]
 
+      # @!method fuse_configure
+      #  @abstract
+      #  Called immediately before the filesystem is mounted, after options have been parsed
+      #
+      #  @raise [Error] to prevent the mount from proceeding
+      #  @return [void]
+
       # @!endgroup
 
       # @!visibility private