ffi-libfuse 0.0.1.pre

data/lib/ffi/libfuse/adapter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    # This namespace contains helper Modules that alter the signature or behaviour of the native {FuseOperations}
+    # callbacks
+    #
+    # There are two types of Adapters
+    #
+    # 1) Wrap many fuse methods in a proc that manipulates the arguments in a consistent way
+    #
+    #    These will implement {FuseOperations#fuse_wrappers} to add the proc which can then...
+    #
+    #    * prepend additional arguments - eg. ({Context})
+    #    * wrap common arguments - eg. ({Pathname})
+    #    * handle return values/exceptions - eg. ({Safe})
+    #    * or just wrap the underlying block - eg. ({Debug})
+    #
+    # 2) Override specific callback methods to change their signatures
+    #
+    #    These will prepend an internal module that implements the callback methods,  manipulating the
+    #    argument list and passing on to super and then manipulating the result.
+    #
+    #    The prepend module must include Adapter so that the module methods themselves do not register as
+    #    callbacks unless there is an implementation by the including class.
+    #
+    #    eg. {Ruby}, {Fuse2Compat}, {Fuse3Support}
+    module Adapter
+      # Does something other than an adapter (ie the underlying filesystem itself) implement fuse_method.
+      #
+      # Can be called by custom implementations of fuse_respond_to? to confirm that the implementing module
+      # is not a type 2 Adapter (which itself will call super)
+      def fuse_super_respond_to?(fuse_method)
+        return false unless respond_to?(fuse_method)
+
+        m = method(fuse_method)
+        m = m.super_method while m && Adapter.include?(m.owner)
+
+        m && true
+      end
+
+      # @!visibility private
+
+      # Use {#fuse_super_respond_to?} if no super implementation
+      def fuse_respond_to?(fuse_method)
+        return super if defined?(super)
+
+        fuse_super_respond_to?(fuse_method)
+      end
+
+      class << self
+        # @!visibility private
+
+        # is mod an Adapter
+        def include?(mod)
+          adapters.include?(mod)
+        end
+
+        def included(mod)
+          adapters << mod
+        end
+
+        def adapters
+          # Avoid Kernel#open being considered a fuse callback
+          @adapters ||= [Kernel, Object, BasicObject]
+        end
+      end
+    end
+  end
+end
+
+require_relative 'adapter/context'
+require_relative 'adapter/thread_local_context'
+require_relative 'adapter/debug'
+require_relative 'adapter/ruby'
+require_relative 'adapter/interrupt'
+require_relative 'adapter/pathname'
+require_relative 'adapter/fuse3_support'
+require_relative 'adapter/fuse2_compat'

data/lib/ffi/libfuse/callbacks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    # Methods to register callbacks and wrappers
+    module Callbacks
+      # Registers block as a callback method
+      #
+      # @note wrappers are defined in inside out order
+      #
+      # @param [Symbol] method the callback being registered
+      # @param [Array<Proc,Hash<:wrapper,:excludes>,Object>] wrappers with each entry being
+      #
+      #  - a Proc(method, *args, &block)
+      #
+      #      either handling the callback itself or yielding *args (possibly after manipulation) onwards to &block.
+      #       Do not include method in the yield args!
+      #  - a Hash with keys
+      #
+      #      - wrapper: [Proc] as above
+      #      - excludes: [Array<Symbol>] names of methods that the proc should not apply to. Useful when registering
+      #        the same list of wrappers for many methods
+      #  - an Object responding to #method(*args,&block)
+      #
+      # @param [Proc] block if provided is used as the innermost block to handle the callback - equivalent to
+      #  being the first entry in wrappers list
+      def register(method, wrappers = [], &block)
+        callback = wrappers.each.inject(block) do |b, w|
+          next wrap_callback(method, **w, &b) if w.is_a?(Hash)
+
+          wrap_callback(method, w, &b)
+        end
+        send(:[]=, method, callback)
+      end
+
+      private
+
+      def initialize_callbacks(callbacks, delegate:, wrappers: [])
+        callbacks.select { |m| respond_to_callback?(m, delegate) }.each do |m|
+          register(m, wrappers) { |*f_args| delegate.send(m, *f_args) }
+        end
+      end
+
+      def respond_to_callback?(method, delegate)
+        delegate.respond_to?(method)
+      end
+
+      def wrap_callback(method, proc_wrapper = nil, wrapper: proc_wrapper, excludes: [], &block)
+        return block if excludes.include?(method)
+
+        # Wrapper proc takes fuse_method as first arg, but the resulting proc only takes the callback args
+        # ie so wrappers should not yield the fuse_method onwards!!
+        return proc { |*args| wrapper.call(method, *args, &block) } if wrapper.is_a?(Proc)
+
+        return proc { |*args| wrapper.send(method, *args, &block) } if wrapper.respond_to?(method)
+
+        block
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/fuse2.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+require_relative 'fuse_operations'
+require_relative 'fuse_args'
+require_relative 'fuse_common'
+require_relative '../ruby_object'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    raise "Cannot load Fuse2 for #{FUSE_VERSION}" unless FUSE_MAJOR_VERSION == 2
+
+    typedef :pointer, :chan
+    typedef :pointer, :cmd
+
+    attach_function :fuse_parse_cmdline2, :fuse_parse_cmdline, [FuseArgs.by_ref, :pointer, :pointer, :pointer], :int
+    attach_function :fuse_mount2, :fuse_mount, [:string, FuseArgs.by_ref], :chan
+    attach_function :fuse_new2, :fuse_new, [:chan, FuseArgs.by_ref, FuseOperations.by_ref, :size_t, RubyObject], :fuse
+    attach_function :fuse_chan_fd, [:chan], :int
+    attach_function :fuse_read_cmd, [:fuse], :cmd, blocking: true
+    attach_function :fuse_process_cmd, %i[fuse cmd], :void, blocking: true
+    attach_function :fuse_exited2, :fuse_exited, [:fuse], :int
+    attach_function :fuse_unmount2, :fuse_unmount, %i[string chan], :void
+    attach_function :fuse_loop_mt2, :fuse_loop_mt, [:fuse], :int, blocking: true
+
+    class << self
+      # @!visibility private
+      # @!method fuse_parse_cmdline2
+      # @!method fuse_mount2
+      # @!method fuse_new2
+      # @!method fuse_chan_fd
+      # @!method fuse_read_cmd
+      # @!method fuse_process_cmd
+      # @!method fuse_exited2
+      # @!method fuse_unmount2
+      # @!method fuse_loop_mt2
+    end
+
+    # Helper class to managed a mounted fuse filesystem
+    # @!visibility private
+    class Fuse2 < FuseCommon
+      class << self
+        def parse_cmdline(args, handler: nil)
+          # This also handles -h to print help information on stderr
+          # Parse mountpoint, -f , -s from args
+          # @return [Array<(String,Boolean,Boolean)>|nil]
+          #     mountpoint, multi_thread, foreground options from args if available
+          #     nil if no mountpoint, or options is requesting help or version information
+          mountpoint_ptr = FFI::MemoryPointer.new(:pointer, 1)
+          multi_thread_ptr = FFI::MemoryPointer.new(:int, 1)
+          foreground_ptr = FFI::MemoryPointer.new(:int, 1)
+
+          return nil unless Libfuse.fuse_parse_cmdline2(args, mountpoint_ptr, multi_thread_ptr, foreground_ptr).zero?
+
+          # noinspection RubyResolve
+          mp_data_ptr = mountpoint_ptr.get_pointer(0)
+
+          mountpoint = mp_data_ptr.read_string unless mp_data_ptr.null?
+
+          multi_thread = multi_thread_ptr.get(:int, 0) == 1
+          foreground = foreground_ptr.get(:int, 0) == 1
+
+          result = { mountpoint: mountpoint, single_thread: !multi_thread, foreground: foreground }
+          args.parse!(Main::STANDARD_OPTIONS, [result, handler]) { |*proc_args| fuse_opt_proc(*proc_args) }
+          result
+        end
+
+        # Handle standard custom args
+        def fuse_opt_proc(custom, _arg, key, _outargs)
+          return :keep if %i[unmatched non_option].include?(key)
+
+          run_args, handler = custom
+          case key
+          when :show_help
+            warn Main::HELP
+            if handler.respond_to?(:fuse_help) && (help = handler.fuse_help)
+              warn help
+            end
+          when :debug
+            handler.fuse_debug(true) if handler.respond_to?(:fuse_debug)
+          when :show_version
+            warn Main.version
+            if handler.respond_to?(:fuse_version) && (version = handler.fuse_version)
+              warn version
+            end
+          else
+            return :keep
+          end
+          run_args[key] = true
+          :keep
+        end
+
+        def finalize_fuse(fuse, mountpoint, fuse_ch)
+          proc do
+            Libfuse.fuse_unmount2(mountpoint, fuse_ch) if fuse_ch
+            Libfuse.fuse_destroy(fuse) if fuse
+          end
+        end
+      end
+
+      attr_reader :mountpoint
+
+      # Have we requested an unmount (note not actually checking if OS sees the fs as mounted)
+      def mounted?
+        @fuse && Libfuse.fuse_exited2(@fuse).zero?
+      end
+
+      def initialize(mountpoint, args, operations, private_data)
+        super()
+        @mountpoint = mountpoint
+
+        # Hang on to our ops and private data
+        @operations = operations
+
+        # Note this outputs the module args.
+        @ch = Libfuse.fuse_mount2(@mountpoint, args)
+        @ch = nil if @ch&.null?
+        if @ch
+          @fuse = Libfuse.fuse_new2(@ch, args, @operations, @operations.size, private_data)
+          @fuse = nil if @fuse&.null?
+        end
+      ensure
+        # if we unmount/destroy in the finalizer then the private_data object cannot be used in destory
+        # as it's weakref will have been GC'd
+        ObjectSpace.define_finalizer(self, self.class.finalize_fuse(@fuse, @mountpoint, @ch))
+      end
+
+      # [IO] /dev/fuse file descriptor for use with IO.select
+      def io
+        # The FD is created (and destroyed?) by FUSE so we don't want ruby to do anything with it during GC
+        @io ||= ::IO.for_fd(Libfuse.fuse_chan_fd(@ch), 'r', autoclose: false)
+      end
+
+      def process
+        cmd = Libfuse.fuse_read_cmd(@fuse)
+        Libfuse.fuse_process_cmd(@fuse, cmd) if cmd && !cmd.null?
+
+        # return true unless fuse has exited.
+        Libfuse.fuse_exited2(@fuse).zero?
+      end
+
+      private
+
+      def native_fuse_loop_mt(**_options)
+        Libfuse.fuse_loop_mt2(@fuse)
+      end
+
+      def unmount
+        c = @ch
+        @ch = nil
+        Libfuse.fuse_unmount2(mountpoint, c) if c
+      end
+    end
+
+    # @!visibility private
+    Fuse = Fuse2
+  end
+end

data/lib/ffi/libfuse/fuse3.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_common'
+require_relative 'fuse_cmdline_opts'
+require_relative 'fuse_loop_config'
+require_relative 'fuse_args'
+require_relative 'fuse_operations'
+require_relative '../ruby_object'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    raise "Cannot load Fuse3 for #{FUSE_VERSION}" unless FUSE_MAJOR_VERSION == 3
+
+    attach_function :fuse_parse_cmdline3,
+                    :fuse_parse_cmdline, [FuseArgs.by_ref, FuseCmdlineOpts.by_ref], :int
+    attach_function :fuse_cmdline_help, [], :void
+    attach_function :fuse_lowlevel_help, [], :void
+    attach_function :fuse_lib_help, [FuseArgs.by_ref], :void
+    attach_function :fuse_pkgversion, [], :string
+    attach_function :fuse_lowlevel_version, [], :void
+    attach_function :fuse_new3,
+                    :fuse_new, [FuseArgs.by_ref, FuseOperations.by_ref, :size_t, RubyObject], :fuse
+    attach_function :fuse_mount3, :fuse_mount, %i[fuse string], :int
+    attach_function :fuse_loop_mt3,
+                    :fuse_loop_mt, [:fuse, FuseLoopConfig.by_ref], :int, blocking: true
+    attach_function :fuse_session_fd, [:session], :int
+    attach_function :fuse_session_exit, [:session], :void
+    attach_function :fuse_session_exited, [:session], :int
+    attach_function :fuse_unmount3, :fuse_unmount, %i[fuse], :void
+    attach_function :fuse_session_receive_buf, [:session, FuseBuf.by_ref], :int, blocking: true
+    attach_function :fuse_session_process_buf, [:session, FuseBuf.by_ref], :void, blocking: true
+
+    class << self
+      # @!visibility private
+      # @!method fuse_parse_cmdline3
+      # @!method fuse_cmdline_help
+      # @!method fuse_lowlevel_help
+      # @!method fuse_lib_help
+      # @!method fuse_pkgversion
+      # @!method fuse_lowlevel_version
+      # @!method fuse_new3
+      # @!method fuse_mount3
+      # @!method fuse_loop_mt3
+      # @!method fuse_session_fd
+      # @!method fuse_session_exit
+      # @!method fuse_session_exited
+      # @!method fuse_unmount3
+      # @!method fuse_session_receive_buf
+      # @!method fuse_session_process_buf
+    end
+
+    # Helper class to managed a mounted fuse filesystem
+    # @!visibility private
+    class Fuse3 < FuseCommon
+      class << self
+        def parse_cmdline(args, handler: nil)
+          cmdline_opts = FuseCmdlineOpts.new
+          Libfuse.fuse_parse_cmdline3(args, cmdline_opts)
+
+          handler&.fuse_debug(cmdline_opts.debug) if handler.respond_to?(:fuse_debug)
+
+          # mimics fuse_main which exits after printing version info, even if -h
+          if cmdline_opts.show_version
+            show_version(handler)
+          elsif cmdline_opts.show_help
+            show_help(args, handler)
+          end
+
+          cmdline_opts.to_h
+        end
+
+        def show_version(handler)
+          $stdout.puts "FUSE library version #{Libfuse.fuse_pkgversion}"
+          Libfuse.fuse_lowlevel_version
+          $stdout.puts Main.version
+          $stdout.puts handler.fuse_version if handler.respond_to?(:fuse_version)
+        end
+
+        def show_help(args, handler)
+          $stdout.puts "usage: #{args.argv.first} [options] <mountpoint>\n\n"
+          $stdout.puts "FUSE options:\n"
+          Libfuse.fuse_cmdline_help
+          Libfuse.fuse_lib_help(args)
+          $stdout.puts "\n"
+          $stdout.puts Main::HELP
+          $stdout.puts "\n#{handler.fuse_help}" if handler.respond_to?(:fuse_help)
+        end
+
+        def finalize_fuse(fuse)
+          proc do
+            if fuse
+              Libfuse.fuse_unmount3(fuse)
+              Libfuse.fuse_destroy(fuse)
+            end
+          end
+        end
+      end
+
+      attr_reader :mountpoint
+
+      # Have we requested an unmount (note not actually checking if OS sees the fs as mounted)
+      def mounted?
+        (se = session) && Libfuse.fuse_session_exited(se).zero?
+      end
+
+      def initialize(mountpoint, args, operations, private_data)
+        super()
+        warn 'No mountpoint provided' unless mountpoint
+        return unless mountpoint
+
+        @mountpoint = mountpoint
+
+        # Hang on to our ops and private data
+        @operations = operations
+
+        @fuse = Libfuse.fuse_new3(args, @operations, @operations.size, private_data)
+        @fuse = nil if @fuse&.null?
+
+        @mounted = @fuse && Libfuse.fuse_mount3(@fuse, @mountpoint).zero?
+      ensure
+        # if we unmount/destroy in the finalizer then the private_data object cannot be used in destroy
+        # as it's weakref will have been GC'd
+        ObjectSpace.define_finalizer(self, self.class.finalize_fuse(@fuse))
+      end
+
+      def process
+        buf = Thread.current[:fuse_buffer] ||= FuseBuf.new
+        se = Thread.current[:fuse_session] ||= session
+
+        res = Libfuse.fuse_session_receive_buf(se, buf)
+
+        # errors, or exiting
+        return false if res.negative?
+
+        Libfuse.fuse_session_process_buf(se, buf) if res.positive?
+
+        # return true unless fuse has exited.
+        Libfuse.fuse_session_exited(se).zero?
+      end
+
+      # [IO] /dev/fuse file descriptor for use with IO.select
+      def io
+        # The FD is created (and destroyed?) by FUSE so we don't want ruby to do anything with it during GC
+        @io ||= ::IO.for_fd(Libfuse.fuse_session_fd(session), 'r', autoclose: false)
+      end
+
+      private
+
+      def native_fuse_loop_mt(max_idle_threads: 10, **_options)
+        Libfuse.fuse_loop_mt3(@fuse, FuseLoopConfig.new.fill(max_idle: max_idle_threads))
+      end
+
+      def unmount
+        Libfuse.fuse_unmount3(@fuse) if @mounted && @fuse && !@fuse.null?
+      end
+    end
+
+    # @!visibility private
+    Fuse = Fuse3
+  end
+end