ffi-libfuse 0.0.1.pre

data/lib/ffi/libfuse/fuse_args.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+require_relative 'fuse_opt'
+require_relative '../ruby_object'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    # struct fuse_args
+    class FuseArgs < FFI::Struct
+      layout :argc, :int, :argv, :pointer, :allocated, :int
+
+      # Create an fuse_args struct from command line options
+      # @param [Array<String>] argv command line args
+      #   args[0] is expected to be program name
+      # @return [FuseArgs]
+      def self.create(*argv)
+        new.fill(*argv)
+      end
+
+      # @!visibility private
+      # noinspection RubyResolve
+      def fill(*argv)
+        # Keep the args allocated while in scope
+        @arg_vector = FFI::MemoryPointer.new(:pointer, argv.size + 1)
+        @argv_strings = argv.map { |k| FFI::MemoryPointer.from_string(k.to_s) }
+        @arg_vector.write_array_of_pointer(@argv_strings)
+        @arg_vector[argv.size].put_pointer(0, FFI::Pointer::NULL)
+        self[:argv] = @arg_vector
+        self[:argc] = argv.size
+        self[:allocated] = 0
+        self
+      end
+
+      # @!attribute [r] argc
+      #  @return [Integer] count of args
+      def argc
+        self[:argc]
+      end
+
+      # @!attribute [r] argv
+      #  @return [Array<String>]
+      def argv
+        # noinspection RubyResolve
+        self[:argv].get_array_of_pointer(0, argc).map(&:read_string)
+      end
+
+      # @!visibility private
+      def allocated
+        self[:allocated]
+      end
+
+      # @!visibility private
+      def inspect
+        "#{self.class.name} - #{%i[argc argv allocated].map { |m| [m, send(m)] }.to_h}"
+      end
+
+      # Add an arg to this arg list
+      # @param [String] arg
+      def add(arg)
+        Libfuse.fuse_opt_add_arg(self, arg)
+      end
+
+      # Insert arg at pos in this struct via fuse_opt_insert_arg
+      # @param [Integer] pos index to insert arg at
+      # @param [String] arg
+      def insert(pos, arg)
+        Libfuse.fuse_opt_insert_arg(self, pos, arg)
+      end
+
+      #
+      # Option parsing function
+      #
+      # @param [Hash<String,Symbol>] opts option schema
+      #
+      #  hash keys are a String template to match arguments against
+      #
+      #  1. "-x", "-foo", "--foo", "--foo-bar", etc.	These match only themselves.  Invalid values are "--" and anything
+      #     beginning with "-o"
+      #  2. "foo", "foo-bar", etc.  These match "-ofoo", "-ofoo-bar" or the relevant option in a comma separated option
+      #     list
+      #  3. "bar=", "--foo=", etc.  These are variations of 1) and 2) which have a parameter
+      #  4. '%' Formats Not Supported (or needed for Ruby!)
+      #  5. "-x ", etc.  Matches either "-xparam" or "-x param" as two separate arguments
+      #  6. '%' Formats Not Supported
+      #
+      #  hash values are the Symbol sent to the block for a matching argument
+      #
+      #  - :keep Argument is not passed to block, but behave as if the block returns :keep
+      #  - :discard Argument is not passed to block, but behave as if the block returns :discard
+      #  - any other value is yielded as 'key' property on matching argument
+      #
+      # @param [Object] data an optional object that will be passed thru to the block
+      #
+      # @yieldparam [Object] data
+      # @yieldparam [String] arg is the whole argument or option including the parameter if exists.
+      #
+      #  A two-argument option ("-x foo") is always converted to single argument option of the form "-xfoo" before this
+      #  function is called.
+      #
+      #  Options of the form '-ofoo' are yielded without the '-o' prefix.
+      #
+      # @yieldparam [Symbol] key determines why the processing function was called
+      #
+      #  - :unmatched for arguments that *do not match* any supplied option
+      #  - :non_option for non-option arguments (after -- or not beginning with -)
+      #  - with appropriate value from opts hash for a matching argument
+      #
+      # @yieldparam [FuseArgs] outargs can {add} or {insert} additional args as required
+      #
+      #  eg. if one arg implies another
+      #
+      # @yieldreturn [Symbol] the argument action
+      #
+      #  - :error            an error
+      #  - :keep             the current argument (to pass on further)
+      #  - :handled,:discard success and discard the current argument (ie because it has been handled)
+      #
+      # @return [nil|FuseArgs] nil on error, self on success
+      def parse!(opts, data = nil, &block)
+        # turn option value symbols into integers including special negative values from fuse_opt.h
+        symbols = opts.values.uniq + %i[discard keep non_option unmatched]
+
+        int_opts = opts.transform_values do |v|
+          %i[discard keep].include?(v) ? symbols.rindex(v) - symbols.size : symbols.index(v)
+        end
+
+        fop = proc { |d, arg, key, outargs| fuse_opt_proc(d, arg, symbols[key], outargs, &block) }
+        result = Libfuse.fuse_opt_parse(self, data, int_opts, fop)
+
+        result.zero? ? self : nil
+      end
+
+      private
+
+      # Valid return values from parse! block
+      FUSE_OPT_PROC_RETURN = { error: -1, keep: 1, handled: 0, discard: 0 }.freeze
+
+      def fuse_opt_proc(data, arg, key, out, &block)
+        res = block.call(data, arg, key, out)
+        res.is_a?(Integer) ? res : FUSE_OPT_PROC_RETURN.fetch(res)
+      rescue KeyError => e
+        warn "FuseOptProc error - Unknown result  #{e.key}"
+        -1
+      rescue StandardError => e
+        warn "FuseOptProc error - #{e.class.name}:#{e.message}"
+        -1
+      end
+    end
+
+    # typedef int (*fuse_opt_proc_t)(void *data, const char *arg, int key, struct fuse_args *outargs);
+    callback :fuse_opt_proc_t, [RubyObject, :string, :int, FuseArgs.by_ref], :int
+
+    attach_function :fuse_opt_parse, [FuseArgs.by_ref, RubyObject, FuseOpt::OptList, :fuse_opt_proc_t], :int
+    attach_function :fuse_opt_add_arg, [FuseArgs.by_ref, :string], :int
+    attach_function :fuse_opt_insert_arg, [FuseArgs.by_ref, :int, :string], :int
+
+    class << self
+      # @!visibility private
+      # @!method fuse_opt_parse
+      # @!method fuse_opt_add_arg
+      # @!method fuse_opt_insert_arg
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_buffer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    bitmask :fuse_buf_flags, [:is_fd, 1, :fd_seek, :fd_retry]
+    bitmask :fuse_buf_copy_flags, [:no_splice, 1, :force_splice, 2, :splice_move, 4, :splice_nonblock, 8]
+
+    #
+    # Single data buffer
+    #
+    # Generic data buffer for I/O, extended attributes, etc...Data may be supplied as a memory pointer or as a file
+    #  descriptor
+    #
+    # @todo define helper methods to create buffers pointing to file_descriptors or allocated memory
+    class FuseBuf < FFI::Struct
+      layout(
+        size: :size_t, #  Size of data in bytes
+        flags: :fuse_buf_flags, # Buffer flags
+        mem: :pointer, # Memory pointer - used if :is_fd flag is not set
+        fd: :int, # File descriptor - used if :is_fd is set
+        pos: :off_t # File position - used if :fd_seek flag is set.
+      )
+
+      # rubocop:disable  Naming/MethodParameterName
+
+      # @param [Integer] size Size of data in bytes
+      # @param [Integer] fd File descriptor
+      # @param [FFI::Pointer] mem Memory pointer
+      # @param [Boolean] fd_retry
+      #  Retry operation on file descriptor
+      #
+      #  If this flag is set then retry operation on file descriptor until .size bytes have been copied or an error or
+      #  EOF is detected.
+      #
+      # @param [Integer] pos
+      #  If > 0 then used to seek to the given offset before performing operation on file descriptor.
+      # @return [self]
+      def fill(size:, mem: FFI::Pointer::NULL, fd: -1, fd_retry: false, pos: 0)
+        self[:size] = size
+        self[:mem] = mem
+        self[:fd] = fd
+        flags = []
+        flags << :is_fd if fd != -1
+        flags << :fd_seek if pos.positive?
+        flags << :fd_retry if fd_retry
+        self[:flags] = flags
+        self[:pos] = pos
+        self
+      end
+    end
+    # rubocop:enable Naming/MethodParameterName
+
+    #
+    # Data buffer vector
+    #
+    # An array of data buffers, each containing a memory pointer or a file descriptor.
+    #
+    # Allocate dynamically to add more than one buffer.
+    #
+    # @todo find a use for {FuseOperations#read_buf} and implement necessary helpers
+    class FuseBufVec < FFI::Struct
+      layout(
+        count: :size_t,
+        idx: :size_t,
+        off: :size_t,
+        buf: :pointer
+      )
+      # @!attribute [r] count
+      #   @todo implement
+      #   @return [Integer] the number of buffers in the array
+
+      # @!attribute [r] index
+      #   @todo implement
+      #   @return [Integer] index of current buffer within the array
+
+      # @!attribute [r] offset
+      #   @todo implement
+      #   @return [Integer] current offset within the current buffer
+
+      # @!attribute [r] buffers
+      #   @todo implement
+      #   @return [Array<FuseBuf>] array of buffers
+
+      # @see #init
+      def self.init(**buf_options)
+        new.init(**buf_options)
+      end
+
+      # Allocate a vector containing a single buffer
+      #
+      # See fuse_common.h FUSE_BUFVEC_INIT macro
+      # @param [Hash<Symbol,Object>] buf_options see {FuseBuf.fill}
+      def init(**buf_options)
+        self[:count] = 1
+        self[:idx] = 0
+        self[:off] = 0
+        self[:buf] = FuseBuf.new.fill(**buf_options), to_ptr
+        self
+      end
+
+      # @return [Integer] total size of data in a fuse buffer vector
+      def buf_size
+        Libfuse.fuse_buf_size(self)
+      end
+
+      # Copy data from one buffer vector to another
+      # @param [FuseBufVec] dst Destination buffer vector
+      # @param [Array<Symbol>] flags Buffer copy flags
+      #  - :no_splice
+      #    Don't use splice(2)
+      #
+      #    Always fall back to using read and write instead of splice(2) to copy data from one file descriptor to
+      #    another.
+      #
+      #    If this flag is not set, then only fall back if splice is unavailable.
+      #
+      #  - :force_splice
+      #
+      #    Always use splice(2) to copy data from one file descriptor to another.  If splice is not available, return
+      #    -EINVAL.
+      #
+      #  - :splice_move
+      #
+      #    Try to move data with splice.
+      #
+      #    If splice is used, try to move pages from the source to the destination instead of copying. See
+      #    documentation of SPLICE_F_MOVE in splice(2) man page.
+      #
+      #  - :splice_nonblock
+      #
+      #    Don't block on the pipe when copying data with splice
+      #
+      #    Makes the operations on the pipe non-blocking (if the pipe is full or empty).  See SPLICE_F_NONBLOCK in
+      #    the splice(2) man page.
+      #
+      # @return [Integer] actual number of bytes copied or -errno on error
+      #
+      def copy_to(dst, *flags)
+        Libfuse.fuse_buf_copy(dst, self, flags)
+      end
+    end
+
+    attach_function :fuse_buf_size, [FuseBufVec.by_ref], :size_t
+    attach_function :fuse_buf_copy, [FuseBufVec.by_ref, FuseBufVec.by_ref, :fuse_buf_copy_flags], :ssize_t
+
+    class << self
+      # @!visibility private
+      # @!method fuse_buf_size
+      # @!method fuse_buf_copy
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_callbacks.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'callbacks'
+
+module FFI
+  module Libfuse
+    # Methods to register callbacks and wrappers
+    module FuseCallbacks
+      include Callbacks
+
+      # @!group Configuration
+
+      # @!method fuse_wrappers(*wrappers)
+      #  @abstract
+      #  Wrappers change the behaviour/signature of the abstract fuse callback methods
+      #
+      #  @param [Array] wrappers
+      #    An initial list of wrappers
+      #  @return [Array] the final list of wrappers.
+      #    Implementations should append or prepend to the input wrappers as appropriate
+      #
+      #    See {register} for what constitutes a valid wrapper
+
+      # @!method fuse_respond_to?(fuse_method)
+      #   @abstract
+      #   @param [Symbol] fuse_method a fuse callback method
+      #   @return [Boolean] true if the fuse method should be registered
+
+      # @!endgroup
+      private
+
+      def initialize_callbacks(delegate:, wrappers: [])
+        wrappers = delegate.fuse_wrappers(*wrappers) if delegate.respond_to?(:fuse_wrappers)
+        super(callback_members, delegate: delegate, wrappers: wrappers)
+      end
+
+      def respond_to_callback?(method, delegate)
+        return delegate.fuse_respond_to?(method) if delegate.respond_to?(:fuse_respond_to?)
+
+        super
+      end
+
+      def callback_members
+        members - [:flags]
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_cmdline_opts.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../accessors'
+require_relative 'fuse_loop_config'
+module FFI
+  module Libfuse
+    #
+    # struct fuse_cmdline_opts {
+    #   int singlethread;
+    #   int foreground;
+    #   int debug;
+    #   int nodefault_subtype;
+    #   char *mountpoint;
+    #   int show_version;
+    #   int show_help;
+    #   int clone_fd;
+    #   unsigned int max_idle_threads;
+    # };
+    # @!visibility private
+    class FuseCmdlineOpts < FFI::Struct
+      include(FFI::Accessors)
+
+      layout(
+        single_thread: :int,
+        foreground: :int,
+        debug: :int,
+        nodefault_subtype: :int,
+        mountpoint: :string,
+        show_version: :int,
+        show_help: :int,
+        clone_fd: :int,
+        max_idle_threads: :int
+      )
+
+      # int to booleans
+      ffi_attr_reader(:single_thread, :foreground, :debug, :nodefault_subtype, :show_version, :show_help,
+                      :clone_fd) do |v|
+        v != 0
+      end
+
+      ffi_attr_reader(:max_idle_threads, :mountpoint)
+    end
+  end
+end

data/lib/ffi/libfuse/fuse_common.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+require_relative 'thread_pool'
+require_relative 'ackbar'
+
+module FFI
+  # Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
+  module Libfuse
+    typedef :pointer, :fuse
+    typedef :pointer, :session
+
+    attach_function :fuse_get_session, [:fuse], :session
+    attach_function :fuse_set_signal_handlers, [:session], :int
+    attach_function :fuse_remove_signal_handlers, [:session], :void
+    attach_function :fuse_loop, [:fuse], :int, blocking: false
+    attach_function :fuse_clean_cache, [:fuse], :int
+    attach_function :fuse_exit, [:fuse], :void
+    attach_function :fuse_destroy, [:fuse], :void
+    attach_function :fuse_daemonize, [:int], :int
+
+    class << self
+      # @!visibility private
+      # @!method fuse_get_session(fuse)
+      # @!method fuse_set_signal_handlers(session)
+      # @!method fuse_remove_signal_handlers(session)
+      # @!method fuse_loop(fuse)
+      # @!method fuse_clean_cache(fuse)
+      # @!method fuse_exit(fuse)
+      # @!method fuse_destroy(fuse) void
+      # @!method fuse_daemonize(foreground) int
+    end
+
+    # @abstract Base class for Fuse, which itself is just a constant pointing to Fuse2 or Fuse3
+    # @note This class documents the Ruby re-implementation of native fuse functions. It will not generally be used
+    #  directly.
+    class FuseCommon
+      # Run the mounted filesystem until exit
+      # @param [Boolean] native should we run the C native fuse_loop functions or the ruby implementation
+      # @param [Hash<Symbol,Object>] options passed to {run_native} or {run_ruby}
+      # @return [Integer] an exit code for the fuse process (0 for success)
+      def run(native: false, **options)
+        return false unless mounted?
+
+        if native
+          run_native(**options)
+        else
+          run_ruby(**options)
+        end
+      rescue Errno => e
+        -e.errno
+      rescue StandardError => e
+        warn e
+        warn e.backtrace.join("\n")
+        -1
+      ensure
+        teardown
+      end
+
+      # @api private
+      # @param [Boolean] foreground
+      # @param [Boolean] single_thread
+      # @param [Hash<String,Proc>] traps see {Ackbar.trap}
+      #
+      # Implement fuse loop in ruby
+      #
+      # Pros:
+      #
+      #    * multi-threading works
+      #    * can set max_threads @see https://github.com/libfuse/libfuse/issues/203
+      #    * can send signals to the FS (eg to reload)
+      #    * daemonize works
+      #
+      # Cons:
+      #
+      #    * clone_fd is ignored
+      #    * filesystem interrupts probably can't work
+      def run_ruby(foreground: true, single_thread: true, traps: {}, **options)
+        Ackbar.trap(default_traps.merge(traps)) do |signals|
+          daemonize unless foreground
+
+          if single_thread
+            fuse_loop(signals: signals, **options)
+          else
+            fuse_loop_mt(signals: signals, **options)
+          end
+          0
+        end
+      end
+
+      # Running fuse loop natively
+      #
+      #  Pros
+      #
+      #    * clone_fd will work
+      #    * filesystem interrupts may work
+      #
+      #  Cons
+      #
+      #    * multi-threading will create a new ruby thread for every callback
+      #    * cannot daemonize multi-threaded (hangs) TODO: Why - pthread_lock?, GVL?
+      #    * cannot pass signals to the filesystem
+      #
+      # @api private
+      # @param [Boolean] foreground
+      # @param [Boolean] single_thread
+      #
+      def run_native(foreground: true, single_thread: true, **options)
+        if !single_thread && !foreground
+          warn 'Cannot run native multi-thread fuse_loop when daemonized. Using single_thread mode'
+          single_thread = true
+        end
+
+        clear_default_traps
+        (se = session) && Libfuse.fuse_set_signal_handlers(se)
+
+        Libfuse.fuse_daemonize(foreground ? 1 : 0)
+
+        if single_thread
+          Libfuse.fuse_loop(@fuse)
+        else
+          native_fuse_loop_mt(**options)
+        end
+      ensure
+        (se = session) && Libfuse.fuse_remove_signal_handlers(se)
+      end
+
+      # Tell the processing loop to stop and force unmount the filesystem which is unfortunately required to make
+      # the processing threads, which are mostly blocked on io reads from /dev/fuse fd, to exit.
+      def exit
+        Libfuse.fuse_exit(@fuse) if @fuse
+        # Force threads blocked reading on #io to finish
+        unmount
+      end
+
+      # Ruby implementation of fuse default traps
+      # @see Ackbar
+      def default_traps
+        @default_traps ||= { INT: -> { exit }, HUP: -> { exit }, TERM: -> { exit }, PIPE: 'IGNORE' }
+      end
+
+      # @api private
+      # Ruby implementation of fuse_daemonize which does not work under MRI probably due to the way ruby needs to
+      # understand native threads.
+      def daemonize
+        raise 'Cannot daemonize without support for fork' unless Process.respond_to?(:fork)
+
+        # pipe to wait for fork
+        pr, pw = ::IO.pipe
+
+        if Process.fork
+          # rubocop:disable Style/RescueModifier
+          status = pr.read(1).unpack1('c') rescue 1
+          Kernel.exit!(status)
+          # rubocop:enable Style/RescueModifier
+        end
+
+        begin
+          Process.setsid
+
+          Dir.chdir '/'
+
+          # close/redirect file descriptors
+          $stdin.close
+
+          [$stdout, $stderr].each { |io| io.reopen('/dev/null', 'w') }
+
+          pw.write([0].pack('c'))
+        ensure
+          pw.close
+        end
+      end
+
+      # @api private
+      # Keep track of time until next cache clean for the caching performed by libfuse itself
+      def fuse_clean_cache
+        now = Time.now
+        @next_cache_clean ||= now
+        return @next_cache_clean - now unless now >= @next_cache_clean
+
+        delay = Libfuse.fuse_clean_cache(@fuse)
+        @next_cache_clean = now + delay
+        delay
+      end
+
+      # @api private
+      # Ruby implementation of single threaded fuse loop
+      def fuse_loop(signals:, remember: false, **_options)
+        loop do
+          break unless mounted?
+
+          timeout = remember ? fuse_clean_cache : nil
+
+          ready, _ignore_writable, errors = ::IO.select([io, signals.pr], [], [io], timeout)
+
+          next unless ready || errors
+
+          raise 'FUSE error' unless errors.empty?
+
+          break if ready.include?(io) && !process
+
+          break if ready.include?(signals.pr) && !signals.next
+        rescue Errno::EBADF
+          raise if mounted? # This will occur on exit
+        end
+      end
+
+      # @api private
+      # Ruby implementation of multi threaded fuse loop
+      #
+      # We cannot simulate the clone_fd behaviour of fuse_loop_mt as the required fd is not exposed in the low level
+      # fuse api.
+      #
+      # @see ThreadPool ThreadPool for the mechanism that controls creation and termination of worker threads
+      def fuse_loop_mt(signals:, max_idle_threads: 10, max_threads: nil, remember: false, **_options)
+        # Monitor for signals (and cache cleaning if required)
+
+        signals.monitor { remember ? fuse_clean_cache : nil }
+        ThreadPool.new(name: 'FuseThread', max_idle: max_idle_threads.to_i, max_active: max_threads) { process }.join
+      end
+
+      # @!visibility private
+      def teardown
+        return unless @fuse
+
+        unmount
+        Libfuse.fuse_destroy(@fuse)
+        ObjectSpace.undefine_finalizer(self)
+        @fuse = nil
+      end
+
+      # @!visibility private
+      def session
+        return nil unless @fuse
+
+        @session ||= Libfuse.fuse_get_session(@fuse)
+        @session.null? ? nil : @session
+      end
+
+      # Allow fuse to handle default signals
+      def clear_default_traps
+        %i[INT HUP TERM PIPE].each do |sig|
+          prev = Signal.trap(sig, 'SYSTEM_DEFAULT')
+          Signal.trap(sig, prev) unless prev == 'DEFAULT'
+        end
+      end
+    end
+  end
+end