ffi-libfuse 0.0.1.pre

data/lib/ffi/libfuse/fuse_opt.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+
+module FFI
+  module Libfuse
+    # @!visibility private
+    #
+    # Option description
+    #
+    # @see Args#parse!
+    class FuseOpt < FFI::Struct
+      layout template: :pointer, #  Matching template and optional parameter formatting
+             offset: :ulong, #  Unused in FFI::Libfuse (harder to prepare structs and offsets than just just call block)
+             value: :int # Value to set the variable to, or to be passed as 'key' to the processing function.
+
+      # @!method initialize(address=nil)
+
+      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[:value] = value.to_i
+        self
+      end
+
+      def null
+        # NULL opt to terminate the list
+        self[:template] = FFI::Pointer::NULL
+        self[:offset] = 0
+        self[:value] = 0
+      end
+
+      # @!visibility private
+      # DataConverter for Hash<String,Integer> to Opt[] required by fuse_parse_opt
+      module OptList
+        extend FFI::DataConverter
+        native_type FFI::Type::POINTER
+
+        class << self
+          def to_native(opts, _ctx)
+            raise ArgumentError, "Opts #{opts} must be a Hash" unless opts.respond_to?(:each_pair)
+
+            native = FFI::MemoryPointer.new(:char, FuseOpt.size * (opts.size + 1), false)
+            opts.map.with_index { |(template, key), i| FuseOpt.new(native + (i * FuseOpt.size)).fill(template, key) }
+            FuseOpt.new(native + (opts.size * FuseOpt.size)).null
+
+            native
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_poll_handle.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    attach_function :fuse_notify_poll, [:pointer], :int
+    attach_function :fuse_pollhandle_destroy, [:pointer], :void
+
+    class << self
+      # @!visibility private
+
+      # @!method fuse_notify_poll(ph)
+      # @!method fuse_pollhandle_destroy(ph)
+    end
+
+    # struct fuse_poll_handle
+    # @todo build a filsystem that uses poll and implement an appropriate ruby interface
+    # @see https://libfuse.github.io/doxygen/poll_8c.html
+    class FusePollHandle
+      extend FFI::DataConverter
+      native_type :pointer
+
+      class << self
+        # @!visibility private
+        def from_native(ptr, _ctx)
+          # TODO: we may need a weakref cache on ptr.address so that we don't create different ruby ph for the same
+          #  address, and call destroy on the first one that goes out of scope.
+          new(ptr)
+        end
+
+        # @!visibility private
+        def to_native(value, _ctx)
+          value.ph
+        end
+
+        # @!visibility private
+        def finalizer(pollhandle)
+          proc { Libfuse.fuse_pollhandle_destroy(pollhandle) }
+        end
+      end
+
+      # @!visibility private
+      attr_reader :ph
+
+      # @!visibility private
+      def initialize(pollhandle)
+        @ph = pollhandle
+        ObjectSpace.define_finalizer(self, self.class.finalizer(pollhandle))
+      end
+
+      # @see FuseOperations#poll
+      def notify_poll
+        Libfuse.fuse_notify_poll(ph)
+      end
+      alias notify notify_poll
+      alias fuse_notify_poll notify_poll
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_version.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require_relative '../../ffi/accessors'
+require_relative 'version'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    extend FFI::Library
+
+    # 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]
+    ffi_lib(LIBFUSE)
+
+    # @!scope class
+    # @!method fuse_version()
+    # @return [Integer] the fuse version
+    # See {FUSE_VERSION} which captures this result in a constant
+
+    attach_function :fuse_version, [], :int
+
+    # prior to 3.10 this is Major * 10 + Minor, after 3.10 and later is Major * 100 + Minor
+    # @return [Integer] the version of libfuse
+    FUSE_VERSION = fuse_version
+
+    fv_split = FUSE_VERSION >= 300 ? 100 : 10 # since 3.10
+
+    # @return [Integer] the FUSE major version
+    FUSE_MAJOR_VERSION = FUSE_VERSION / fv_split
+
+    # @return [Integer] the FUSE minor version
+    FUSE_MINOR_VERSION = FUSE_VERSION % fv_split
+
+    if FUSE_MAJOR_VERSION == 2 && FFI::Platform::IS_GNU
+      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
+  end
+end

data/lib/ffi/libfuse/job_pool.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'thread_pool'
+
+module FFI
+  module Libfuse
+    # A JobPool is a ThreadPool whose worker threads are consuming from a Queue
+    class JobPool
+      # Create a Job Pool
+      # @param [Hash<Symbol,Object>] options
+      #  @see ThreadPool.new
+      # @param [Proc] worker the unit of work that will be yielded the scheduled jobs
+      def initialize(**options, &worker)
+        @jq = Queue.new
+        @tp = ThreadPool.new(**options) { (args = @jq.pop) && worker.call(*args) }
+      end
+
+      # Schedule a job
+      # @param [Array<Object>] args
+      # @return [self]
+      def schedule(*args)
+        @jq.push(args)
+        self
+      end
+      alias << schedule
+      alias push schedule
+
+      # Close the JobPool
+      # @return [self]
+      def close
+        @jq.close
+        self
+      end
+
+      # Join the JobPool
+      # @return [self]
+      def join(&block)
+        @tp.join(&block)
+        self
+      end
+
+      # @see ThreadPool#list
+      def list
+        @tp.list
+      end
+
+      # @see ThreadPool#group
+      def group
+        @tp.group
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/main.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_common'
+require_relative 'fuse_args'
+require_relative 'fuse_operations'
+
+module FFI
+  module Libfuse
+    # Controls the main run loop for a FUSE filesystem
+    module Main
+      class << self
+        # Main function of FUSE
+        #
+        # This function:
+        #
+        # - parses command line options - see {fuse_parse_cmdline}
+        #   and exits immediately if help or version options were processed
+        # - 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}
+        #
+        # @param [Array<String>] argv mount.fuse arguments
+        #   expects progname, mountpoint, options....
+        # @param [FuseArgs] args
+        #   alternatively constructed args
+        # @param [Object|FuseOperations] operations
+        #  something that responds to the fuse callbacks and optionally our abstract configuration methods
+        # @param [Object] private_data
+        #  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)
+          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)
+
+          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 2 if !fuse || !mountpoint
+
+          return unless fuse
+
+          warn run_args.to_s if run_args[:debug]
+
+          fuse.run(**run_args)
+        end
+
+        # 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}
+        # - 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
+        # @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)
+          args = fuse_init_args(args)
+
+          # Parse args and print cmdline help
+          run_args = Fuse.parse_cmdline(args, handler: handler)
+
+          # 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
+
+          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]) }
+
+          run_args[:args] = args
+          run_args
+        end
+
+        # @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))
+
+          operations = FuseOperations.new(delegate: operations) unless operations.is_a?(FuseOperations)
+
+          fuse = Fuse.new(mountpoint, 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
+        end
+
+        # @!visibility private
+
+        # Version text
+        def version
+          "#{name}: #{VERSION}"
+        end
+
+        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
+            args = FuseArgs.create(*args)
+          end
+
+          return args if args.is_a?(FuseArgs)
+
+          raise ArgumentError "fuse main args: must be Array<String> or #{FuseArgs.class.name}"
+        end
+      end
+
+      # @!group Abstract Configuration
+
+      # @!method fuse_options
+      #  @abstract
+      #  @return [Hash] custom option schema
+      #  @see FuseArgs#parse!
+
+      # @!method fuse_opt_proc(data,arg,key,out)
+      #  @abstract
+      #  Process custom options
+      #  @see FuseArgs#parse!
+
+      # @!method fuse_traps
+      #  @abstract
+      #  @return [Hash] map of signal name or number to signal handler as per Signal.trap
+
+      # @!method fuse_version
+      #  @abstract
+      #  @return [String] a custom version string to output with -V option
+
+      # @!method fuse_help
+      #  @abstract
+      #  @return [String] help text to explain custom options to show with -h option
+
+      # @!method fuse_debug(enabled)
+      #  @abstract
+      #  Indicate to the filesystem whether debugging option is in use.
+      #  @param [Boolean] enabled if -d option is in use
+      #  @return [void]
+
+      # @!endgroup
+
+      # @!visibility private
+
+      # Standard help options
+      STANDARD_OPTIONS = {
+        '-h' => :show_help, '--help' => :show_help,
+        '-d' => :debug, 'debug' => :debug,
+        '-V' => :show_version, '--version' => :show_version
+      }.freeze
+
+      # Custom options that control how the fuse loop runs
+      RUN_OPTIONS = STANDARD_OPTIONS.merge(
+        {
+          'native' => :native, # Use native libfuse functions for the process loop, primarily for testing
+          'max_threads=' => :max_active,
+          'remember=' => :remember
+        }
+      ).freeze
+
+      # Help text
+      HELP = <<~END_HELP
+        #{name} options:
+            -o max_threads         maximum number of worker threads
+      END_HELP
+    end
+  end
+end

data/lib/ffi/libfuse/test/operations.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../fuse_operations'
+
+module FFI
+  module Libfuse
+    module Test
+      # A FuseOperations that holds callback procs in a Hash rather than FFI objects and allows for direct invocation of
+      # callback methods
+      # @!parse FuseOperations
+      class Operations
+        include FuseCallbacks
+
+        def initialize(delegate:, fuse_wrappers: [])
+          @callbacks = {}
+          initialize_callbacks(delegate: delegate, wrappers: fuse_wrappers)
+        end
+
+        # @!visibility private
+        def [](member)
+          @callbacks[member]
+        end
+
+        # @!visibility private
+        def []=(member, value)
+          @callbacks[member] = value
+        end
+
+        # @!visibility private
+        def members
+          FuseOperations.members
+        end
+
+        private
+
+        # Allow the fuse operations to be called directly - useful for testing
+        # @todo some fancy wrapper to convert tests using Fuse2 signatures when Fuse3 is the loaded library
+        #   and vice-versa
+        def method_missing(method, *args)
+          callback = callback?(method) && self[method]
+          return super unless callback
+
+          callback.call(*args)
+        end
+
+        def respond_to_missing?(method, _private = false)
+          self[method] && callback?(method)
+        end
+
+        def callback?(method)
+          callback_members.include?(method)
+        end
+      end
+    end
+  end
+end