ffi-libfuse 0.0.1.pre → 0.1.0.rc20220550

data/lib/ffi/libfuse/filesystem.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'filesystem/virtual_fs'
+
+module FFI
+  module Libfuse
+    # This module namespace contains classes and modules to assist with building and composing filesystems
+    #
+    # ### Virtual Filesystems
+    # Classes to help compose in-memory filesystems {VirtualFS}, {VirtualDir}, {VirtualFile}
+    #
+    # ### Mapped Filesystem
+    # Modules to map paths in the fuse filesystem to either real files or other filesystem objects
+    # {MappedFiles}, {MappedDir}
+    #
+    # ### Pass-through filesystems
+    # Classes using the mapped modules above to pass fuse callbacks directly to an underlying file/directory
+    # {PassThroughDir}, {PassThroughFile}
+    #
+    # ### Utilities
+    # {Utils} similar to FileUtils to operate directly on filesystem objects, eg to build up initial content
+    module Filesystem
+    end
+  end
+end

data/lib/ffi/libfuse/fuse2.rb

@@ -20,9 +20,9 @@ module FFI
     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_unmount2, :fuse_unmount, %i[string chan], :void, blocking: true
     attach_function :fuse_loop_mt2, :fuse_loop_mt, [:fuse], :int, blocking: true
+    attach_function :fuse_exited2, :fuse_exited, [:fuse], :int
 
     class << self
       # @!visibility private
@@ -62,28 +62,22 @@ module FFI
           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) }
+          args.parse!(Main::STANDARD_OPTIONS, [result, handler]) { |**op_args| fuse_opt_proc(**op_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
+        def fuse_opt_proc(data:, key:, **)
+          run_args, handler = data
           case key
           when :show_help
             warn Main::HELP
-            if handler.respond_to?(:fuse_help) && (help = handler.fuse_help)
-              warn help
-            end
+            warn handler.fuse_help if handler.respond_to?(:fuse_help)
           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
+            warn handler.fuse_version if handler.respond_to?(:fuse_version)
           else
             return :keep
           end
@@ -103,7 +97,7 @@ module FFI
 
       # Have we requested an unmount (note not actually checking if OS sees the fs as mounted)
       def mounted?
-        @fuse && Libfuse.fuse_exited2(@fuse).zero?
+        @fuse && !fuse_exited?
       end
 
       def initialize(mountpoint, args, operations, private_data)
@@ -113,8 +107,8 @@ module FFI
         # Hang on to our ops and private data
         @operations = operations
 
-        # Note this outputs the module args.
-        @ch = Libfuse.fuse_mount2(@mountpoint, args)
+        # Note this outputs the module args. OSX cannot handle null mountpoint with -h/-V
+        @ch = Libfuse.fuse_mount2(@mountpoint || '', args)
         @ch = nil if @ch&.null?
         if @ch
           @fuse = Libfuse.fuse_new2(@ch, args, @operations, @operations.size, private_data)
@@ -132,12 +126,16 @@ module FFI
         @io ||= ::IO.for_fd(Libfuse.fuse_chan_fd(@ch), 'r', autoclose: false)
       end
 
-      def process
+      def fuse_exited?
+        !Libfuse.fuse_exited2(@fuse).zero?
+      end
+
+      def fuse_process
         cmd = Libfuse.fuse_read_cmd(@fuse)
-        Libfuse.fuse_process_cmd(@fuse, cmd) if cmd && !cmd.null?
+        return false if cmd.null?
 
-        # return true unless fuse has exited.
-        Libfuse.fuse_exited2(@fuse).zero?
+        Libfuse.fuse_process_cmd(@fuse, cmd)
+        true
       end
 
       private
@@ -147,9 +145,11 @@ module FFI
       end
 
       def unmount
+        return unless @ch
+
         c = @ch
         @ch = nil
-        Libfuse.fuse_unmount2(mountpoint, c) if c
+        Libfuse.fuse_unmount2(mountpoint, c)
       end
     end
 

data/lib/ffi/libfuse/fuse3.rb

@@ -27,7 +27,7 @@ module FFI
     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_unmount3, :fuse_unmount, %i[fuse], :void, blocking: true
     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
 
@@ -56,7 +56,7 @@ module FFI
       class << self
         def parse_cmdline(args, handler: nil)
           cmdline_opts = FuseCmdlineOpts.new
-          Libfuse.fuse_parse_cmdline3(args, cmdline_opts)
+          return nil unless Libfuse.fuse_parse_cmdline3(args, cmdline_opts).zero?
 
           handler&.fuse_debug(cmdline_opts.debug) if handler.respond_to?(:fuse_debug)
 
@@ -101,7 +101,7 @@ module FFI
 
       # 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?
+        session && !fuse_exited?
       end
 
       def initialize(mountpoint, args, operations, private_data)
@@ -124,19 +124,19 @@ module FFI
         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
+      def fuse_exited?
+        !Libfuse.fuse_session_exited(session).zero?
+      end
 
+      def fuse_process
+        se = session
+        buf = Thread.current[:fuse_buffer] ||= FuseBuf.new
         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 false unless res.positive?
 
-        # return true unless fuse has exited.
-        Libfuse.fuse_session_exited(se).zero?
+        Libfuse.fuse_session_process_buf(se, buf)
+        true
       end
 
       # [IO] /dev/fuse file descriptor for use with IO.select

data/lib/ffi/libfuse/fuse_args.rb

@@ -11,10 +11,13 @@ module FFI
     class FuseArgs < FFI::Struct
       layout :argc, :int, :argv, :pointer, :allocated, :int
 
-      # Create an fuse_args struct from command line options
+      # Create a fuse_args struct from command line options
       # @param [Array<String>] argv command line args
-      #   args[0] is expected to be program name
+      #
+      #   first arg is expected to be program name
       # @return [FuseArgs]
+      # @example
+      #  FFI::Libfuse::FuseArgs.create($0,*ARGV)
       def self.create(*argv)
         new.fill(*argv)
       end
@@ -34,13 +37,13 @@ module FFI
       end
 
       # @!attribute [r] argc
-      #  @return [Integer] count of args
+      # @return [Integer] count of args
       def argc
         self[:argc]
       end
 
       # @!attribute [r] argv
-      #  @return [Array<String>]
+      # @return [Array<String>] list of args
       def argv
         # noinspection RubyResolve
         self[:argv].get_array_of_pointer(0, argc).map(&:read_string)
@@ -53,7 +56,7 @@ module FFI
 
       # @!visibility private
       def inspect
-        "#{self.class.name} - #{%i[argc argv allocated].map { |m| [m, send(m)] }.to_h}"
+        "#{self.class.name} - #{%i[argc argv allocated].to_h { |m| [m, send(m)] }}"
       end
 
       # Add an arg to this arg list
@@ -72,6 +75,8 @@ module FFI
       #
       # Option parsing function
       #
+      # Wraps fuse_opt_parse() in ruby sugar and safety
+      #
       # @param [Hash<String,Symbol>] opts option schema
       #
       #  hash keys are a String template to match arguments against
@@ -80,7 +85,7 @@ module FFI
       #     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
+      #  3. "bar=", "--foo=", etc.  These are variations of 1) and 2) which have a parameter value
       #  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
@@ -91,45 +96,49 @@ module FFI
       #  - :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.
+      #  note that multiple templates can refer to the same key to support multiple option styles
       #
+      # @param [Object] data an optional object that will be passed to the block
+      # @param [Array<Symbol>|nil] ignore
+      #   the keys in this list will be kept without being passed to the block. pass nil to observe all keys
+      # @yield [key:, value:, match:, data:, out:]
+      #   block is called for each remaining arg
       # @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
-      #
+      # @yieldparam [String|Boolean] value the option value or true for option without a value
+      # @yieldparam [String] match the matching template specification (ie a key in opts)
+      # @yieldparam [Object] data
+      # @yieldparam [FuseArgs] out 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
+      #  - :error            an error, alternatively raise {Error}
+      #  - :keep             retain the current argument for further processing
+      #  - :handled,:discard remove the current argument from further processing
+      # @return [nil|self] nil on error otherwise self
+      def parse!(opts, data = nil, ignore: %i[non_option unmatched], &block)
+        ignore ||= []
+
+        # first create an array of unique symbols such that positive indexes are custom options and negative indexes are
+        # special values (see fuse_opt.h), ie so we can turn the integer received in fuse_opt_proc back into a symbol
         symbols = opts.values.uniq + %i[discard keep non_option unmatched]
 
+        # transform our symbol keys into integers suitable for FuseOpts
         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)
+        # keep track of opt templates by key so we extract parameter values from arg
+        param_opts, bool_opts = opts.keys.partition { |t| t =~ /(\s+|=)$/ }.map do |opt_list|
+          opt_list.group_by { |t| opts[t] }
+        end
 
-        result.zero? ? self : nil
+        fop = fuse_opt_proc(symbols, bool_opts, param_opts, ignore, &block)
+        Libfuse.fuse_opt_parse(self, data, int_opts, fop).zero? ? self : nil
       end
 
       private
@@ -137,15 +146,41 @@ module FFI
       # 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)
+      def fuse_opt_proc(symbols, bool_opts, param_opts, ignore, &block)
+        proc do |data, arg, key, out|
+          key = symbols[key]
+          next FUSE_OPT_PROC_RETURN.fetch(:keep) if ignore.include?(key)
+
+          match, value =
+            if %i[unmatched non_option].include?(key)
+              [nil, arg]
+            elsif bool_opts[key]&.include?(arg)
+              [arg, true]
+            elsif (opt = param_opts[key]&.detect { |t| arg.start_with?(t.rstrip) })
+              # Contrary to fuse_opt.h the separating space is not always stripped from these options
+              # https://github.com/libfuse/libfuse/issues/667
+              [opt, arg[opt.rstrip.length..].lstrip]
+            else
+              warn "FuseOptProc error - Cannot match option for #{arg}"
+              next -1
+            end
+
+          safe_opt_proc(key: key, value: value, match: match, data: data, out: out, &block)
+        end
+      end
+
+      def safe_opt_proc(**args, &block)
+        res = block.call(**args)
         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
+        FUSE_OPT_PROC_RETURN.fetch(:error)
+      rescue Error => e
+        warn "#{e.message}: #{args.select { |k, _v| %i[key value].include?(k) }}\n#{argv}"
+        FUSE_OPT_PROC_RETURN.fetch(:error)
+      rescue StandardError, ScriptError => e
+        warn "FuseOptProc error - #{e.class.name}:#{e.message}\n\t#{e.backtrace.join("\n\t")}"
+        FUSE_OPT_PROC_RETURN.fetch(:error)
       end
     end
 

data/lib/ffi/libfuse/fuse_buffer.rb

@@ -14,7 +14,6 @@ module FFI
     # 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
@@ -26,19 +25,60 @@ module FFI
 
       # 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
+      # @!attribute [r] mem
+      #   @return [FFI::Pointer] the memory in the buffer
+      def mem
+        self[:mem]
+      end
+      alias memory mem
+
+      # @!attribute [r] fd
+      #   @return [Integer] the file descriptor number
+      def fd
+        self[:fd]
+      end
+      alias file_descriptor fd
+
+      #  @return [Boolean] true if this a memory buffer
+      def mem?
+        !fd?
+      end
+
+      # @return [Boolean] true if this is a file descriptor buffer
+      def fd?
+        self[:flags].include?(:is_fd)
+      end
+      alias file_descriptor? fd?
+
+      # Resize mem to smaller than initially allocated
+      # @param [Integer] new_size
+      # @return [void]
+      def resize(new_size)
+        self[:size] = new_size
+      end
+
+      # @overload fill(size:, mem:, auto_release)
+      #   Fill as a Memory buffer
+      #   @param [Integer] size Size of data in bytes
+      #   @param [FFI::Pointer] mem Memory pointer allocated to size if required
+      #   @param [Boolean] autorelease
+      #
+      # @overload fill(fd:, fd_retry:, pos:)
+      #   Fill as a FileDescriptor buffer
+      #   @param [Integer] fd File descriptor
+      #   @param [Boolean] fd_retry
+      #     Retry operations 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.
+      #     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.
+      #   @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)
+      def fill(mem: FFI::Pointer::NULL, size: mem.null? ? 0 : mem.size, fd: -1, fd_retry: false, pos: 0)
+        mem = FFI::MemoryPointer.new(:char, size, true) if fd == -1 && mem.null? && size.positive?
+        mem.autorelease = to_ptr.autorelease? unless mem.null?
+
         self[:size] = size
         self[:mem] = mem
         self[:fd] = fd
@@ -60,47 +100,86 @@ module FFI
     #
     # 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
+        # but is treated as a variable length array of FuseBuf at size +1 following the struct.
+        buf: [FuseBuf, 1] # struct fuse_buf[1]
       )
+
       # @!attribute [r] count
-      #   @todo implement
       #   @return [Integer] the number of buffers in the array
+      def count
+        self[:count]
+      end
 
       # @!attribute [r] index
-      #   @todo implement
       #   @return [Integer] index of current buffer within the array
+      def index
+        self[:idx]
+      end
+      alias idx index
 
       # @!attribute [r] offset
-      #   @todo implement
       #   @return [Integer] current offset within the current buffer
+      def offset
+        self[:off]
+      end
+      alias off offset
 
       # @!attribute [r] buffers
-      #   @todo implement
       #   @return [Array<FuseBuf>] array of buffers
+      def buffers
+        @buffers ||= Array.new(count) do |i|
+          next self[:buf].first if i.zero?
+
+          FuseBuf.new(self[:buf].to_ptr + (i * FuseBuf.size))
+        end
+      end
+
+      # @!attribute [r] current
+      #  @return [FuseBuf] the current buffer
+      def current
+        return self[:buf].first if index.zero?
+
+        FuseBuf.new(self[:buf].to_ptr + (index * FuseBuf.size))
+      end
 
-      # @see #init
-      def self.init(**buf_options)
-        new.init(**buf_options)
+      # Create and initialise a new FuseBufVec
+      # @param [Boolean] autorelease should the struct be freed on GC (default NO!!!)
+      # @param [Hash] buf_options options for configuring the initial buffer. See {#init}
+      # @yield(buf,index)
+      # @yieldparam [FuseBuf] buf
+      # @yieldparam [Integer] index
+      # @yieldreturn [void]
+      # @return [FuseBufVec]
+      def self.init(autorelease: true, count: 1, **buf_options)
+        bufvec_ptr = FFI::MemoryPointer.new(:uchar, FuseBufVec.size + (FuseBuf.size * (count - 1)), true)
+        bufvec_ptr.autorelease = autorelease
+        bufvec = new(bufvec_ptr)
+        bufvec[:count] = count
+        bufvec.init(**buf_options)
+
+        buffers.each_with_index { |b, i| yield i, b } if block_given?
+        bufvec
       end
 
-      # Allocate a vector containing a single buffer
+      # Set and initialise a specific 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
+      # @param [Integer] index the index of the buffer
+      #   @param [Hash<Symbol,Object>] buf_options see {FuseBuf#fill}
+      #   @return [FuseBuf] the initial buffer
+      def init(index: 0, **buf_options)
+        self[:idx] = index
         self[:off] = 0
-        self[:buf] = FuseBuf.new.fill(**buf_options), to_ptr
+        current.fill(**buf_options) unless buf_options.empty?
         self
       end
 
+      # Would pref this to be called #size but clashes with FFI::Struct, might need StructWrapper
       # @return [Integer] total size of data in a fuse buffer vector
       def buf_size
         Libfuse.fuse_buf_size(self)
@@ -141,6 +220,29 @@ module FFI
       def copy_to(dst, *flags)
         Libfuse.fuse_buf_copy(dst, self, flags)
       end
+
+      # Copy our data direct to file descriptor
+      # @param [Integer] fileno a file descriptor
+      # @param [Integer] offset
+      # @param [Array<Symbol>] flags - see {copy_to}
+      # @return [Integer] number of bytes copied
+      def copy_to_fd(fileno, offset = 0, *flags)
+        dst = self.class.init(size: buf_size, fd: fileno, pos: offset)
+        copy_to(dst, *flags)
+      end
+
+      # Copy to string via a temporary buffer
+      # @param [Array<Symbol>] flags - see {copy_to}
+      # @return [String] the extracted data
+      def copy_to_str(*flags)
+        dst = FuseBufVec.init(size: buf_size)
+        copied = copy_to(dst, *flags)
+        dst.current.memory.read_string(copied)
+      end
+
+      def copy_from(src, *flags)
+        Libfuse.fuse_buf_copy(self, src, flags)
+      end
     end
 
     attach_function :fuse_buf_size, [FuseBufVec.by_ref], :size_t

data/lib/ffi/libfuse/fuse_callbacks.rb

@@ -31,7 +31,7 @@ module FFI
 
       def initialize_callbacks(delegate:, wrappers: [])
         wrappers = delegate.fuse_wrappers(*wrappers) if delegate.respond_to?(:fuse_wrappers)
-        super(callback_members, delegate: delegate, wrappers: wrappers)
+        super(fuse_callbacks, delegate: delegate, wrappers: wrappers)
       end
 
       def respond_to_callback?(method, delegate)
@@ -39,10 +39,6 @@ module FFI
 
         super
       end
-
-      def callback_members
-        members - [:flags]
-      end
     end
   end
 end