ffi-libfuse 0.0.1.pre

data/lib/ffi/libfuse/ackbar.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'fuse_version'
+
+module FFI
+  module Libfuse
+    # Its a trap!
+    #
+    # Implements the self-pipe trick for handling signals in multi-threaded ruby programs
+    class Ackbar
+      # Read side of the self-pipe
+      # @return [IO] for use with IO.select only
+      # @see monitor
+      # @see next
+      attr_reader :pr
+
+      class << self
+        # Run a block with the given traps, restoring the original traps on completion
+        # @param [Hash] traps map of signal to handler as per Signal.trap
+        # @yieldparam [Ackbar] signals
+        # @return [Object] the result of the block
+        def trap(traps, force: false)
+          signals = new(traps, force: force)
+          yield signals
+        ensure
+          signals&.restore
+        end
+      end
+
+      # @param [Hash<Symbol|String|Integer,String|Proc>] traps
+      #   Map of signal or signo to signal handler as per Signal.trap
+      # @param [Boolean] force
+      #   If not set traps that are not currently set to 'DEFAULT' will be ignored
+      def initialize(traps, force: false, signal: Signal)
+        @signal = signal
+        @traps = traps.transform_keys { |k| signame(k) }
+        @pr, @pw = ::IO.pipe
+        @monitor = nil
+        @restore = @traps.map { |(sig, handler)| [sig, trap(sig, handler, force: force)] }.to_h
+      end
+
+      # Handle the next available signal on the pipe (without blocking)
+      # @return [Boolean] false if pipe is closed, true if pipe would block
+      # @return [Array<String,Object>] signal name, signal result when a signal has been processed
+      def next
+        signame = signal.signame(@pr.read_nonblock(1).unpack1('c'))
+        t = @traps[signame]
+        [signame, t.arity.zero? ? t.call : t.call(signame)]
+      rescue EOFError
+        # the signal pipe writer is closed - we are exiting.
+        @pr.close
+        false
+      rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+        # oh well...
+        true
+      end
+
+      # Restore traps as they were at #new and close the write side of the pipe
+      def restore
+        @restore.each_pair { |signame, handler| signal.trap(signame, handler) }
+        @restore = nil
+        @pw.close
+        @monitor&.join
+      end
+      alias close restore
+
+      # Start a thread to monitor for signals optionally yields between signals
+      # @param [String] name The name of the monitor thread
+      # @yieldreturn [Integer] timeout in seconds or nil to wait until signal or {restore}
+      # @return [Thread] the monitor thread
+      def monitor(name: 'SignalMonitor')
+        @monitor ||= Thread.new do
+          Thread.current.name = name
+          loop do
+            timeout = block_given? ? yield : nil
+
+            ready, _ignore_writable, _errors = ::IO.select([@pr], [], [], timeout)
+
+            break if ready&.include?(@pr) && !self.next
+          end
+        end
+      end
+
+      # @!visibility private
+      # normalize signal identifiers to things that are keys in Signal.list
+      def signame(sig)
+        sig.is_a?(Integer) ? signal.signame(sig) : sig.to_s.upcase.sub(/^SIG/, '')
+      end
+
+      private
+
+      attr_reader :signal
+
+      def trap(signame, handler, force: false)
+        prev =
+          case handler
+          when String, Symbol
+            signal.trap(signame, handler.to_s)
+          else
+            signal.trap(signame) { |signo| send_signal(signo) }
+          end
+
+        signal.trap(signame, prev) unless force || prev == 'DEFAULT'
+        prev
+      end
+
+      def send_signal(signo)
+        @pw&.write([signo].pack('c')) unless @pw&.closed?
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/adapter/context.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../fuse_context'
+
+module FFI
+  module Libfuse
+    module Adapter
+      # Wrapper module to inject {FuseContext} as first arg to each callback method (except :destroy)
+      #
+      # {ThreadLocalContext} may be a less intrusive means to make the context available to callbacks
+      module Context
+        # @!visibility private
+        def fuse_wrappers(*wrappers)
+          wrappers.unshift(
+            {
+              wrapper: proc { |_fm, *args, **_, &b| self.class.context_callback(*args, &b) },
+              excludes: %i[destroy]
+            }
+          )
+          return wrappers unless defined?(super)
+
+          super(*wrappers)
+        end
+
+        module_function
+
+        # @yieldparam [FuseContext] ctx
+        # @yieldparam [Array] *args
+        def context_callback(*args)
+          ctx = FuseContext.get
+          ctx = nil if ctx.null?
+          yield ctx, *args
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/adapter/debug.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    module Adapter
+      # Debug callbacks
+      #
+      # When included in a filesystem class, and if debugging is enabled via {Main#fuse_debug}, then installs a wrapper
+      #  via #{FuseCallbacks#fuse_wrappers} to log callbacks via #warn
+      module Debug
+        DEFAULT_FORMAT = "%<p>s %<n>s %<t>s %<m>s(%<a>s)\n\t=> %<r>s"
+
+        # @return [Boolean] true if debug is enabled
+        def debug?
+          @debug
+        end
+
+        # Configure debug output
+        # @abstract
+        # @return [Hash<Symbol,String>] options to pass to {debug_callback}
+        def debug_config
+          {}
+        end
+
+        # @!visibility private
+        def fuse_wrappers(*wrappers)
+          conf = { prefix: self.class.name }.merge!(debug_config)
+          # validate config for bad formats, strftime etc
+          Debug.debug_format(:test_debug, [], :result, **conf)
+          wrappers << proc { |fm, *args, &b| Debug.debug_callback(fm, *args, **conf, &b) } if debug?
+          return wrappers unless defined?(super)
+
+          super(*wrappers)
+        end
+
+        # @!visibility private
+        def fuse_debug(enabled)
+          super if defined?(super)
+          @debug = enabled
+        end
+
+        module_function
+
+        # Debug fuse method, args and result
+        # @param [Symbol] fuse_method the callback name
+        # @param [Array] args callback arguments
+        # @param [Hash<Symbol,String>] options see {debug} for defaults
+        # @option options [String] prefix
+        # @option options [String] strftime a date time format
+        # @option options [String] format  format string with fields
+        #
+        #   * %<n>: Time.now - use strftime option to control time format
+        #   * %<t>: Thread name
+        #   * %<m>: Fuse method
+        #   * %<a>: Comma separate list of arguments
+        #   * %<r>: Result of the method call (or any error raised)
+        #   * %<p>: The value of prefix option
+        def debug_callback(fuse_method, *args, **options)
+          debug(fuse_method, args, yield(*args), **options)
+        rescue SystemCallError => e
+          # expected behaviour
+          debug(fuse_method, args, "#{e.class.name}(errno=#{e.errno}): #{e.message}", **options)
+          raise
+        rescue StandardError, ScriptError => e
+          # unexpected, debug with backtrace
+          debug(fuse_method, args, (["#{e.class.name}: #{e.message}"] + e.backtrace).join("\n\t"), **options)
+          raise
+        end
+
+        # @!visibility private
+        def debug(fuse_method, args, result, **options)
+          warn debug_format(fuse_method, args, result, **options)
+          result
+        end
+
+        # @!visibility private
+        def debug_format(fuse_method, args, result, prefix: 'DEBUG', strftime: '%FT%T%:z', format: DEFAULT_FORMAT)
+          format(format,
+                 p: prefix,
+                 n: Time.now.strftime(strftime),
+                 t: Thread.current.name || Thread.current,
+                 m: fuse_method,
+                 a: args.map(&:to_s).join(','),
+                 r: result)
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/adapter/fuse2_compat.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    module Adapter
+      # Wrapper module to assist filesystem written for Fuse3 to be compatible with Fuse2
+      module Fuse2Compat
+        # @!visibility private
+        # Wrapper shim for fuse methods to ensure compatibility with Fuse2
+        module Fuse2Prepend
+          include Adapter
+
+          def getattr(path, stat, fuse_file_info = nil)
+            super(path, stat, fuse_file_info)
+          end
+
+          def truncate(path, size, fuse_file_info = nil)
+            super(path, size, fuse_file_info)
+          end
+
+          def init(fuse_conn_info, fuse_config = nil)
+            super(fuse_conn_info, fuse_config)
+          end
+
+          def chown(path, uid, gid, fuse_file_info = nil)
+            super(path, uid, gid, fuse_file_info)
+          end
+
+          def chmod(path, mode, fuse_file_info = nil)
+            super(path, mode, fuse_file_info)
+          end
+
+          def utimens(path, atime, mtime, fuse_file_info = nil)
+            super(path, atime, mtime, fuse_file_info)
+          end
+
+          def readdir(path, buffer, filler, offset, fuse_file_info, fuse_readdir_flag = 0)
+            filler = proc { |buf, name, stat, off = 0, _fuse_fill_dir_flag = 0| filler.call(buf, name, stat, off) }
+            super(path, buffer, filler, offset, fuse_file_info, fuse_readdir_flag)
+          end
+
+          def fgetattr(*args)
+            getattr(*args)
+          end
+
+          def ftruncate(*args)
+            truncate(*args)
+          end
+
+          def fuse_respond_to?(fuse_method)
+            fuse_method = fuse_method[1..].to_sym if %i[fgetattr ftruncate].include?(fuse_method)
+            super(fuse_method)
+          end
+
+          def fuse_flags
+            res = defined?(super) ? super : []
+            if respond_to?(:init_fuse_config)
+              fuse_config = FuseConfig.new
+              init_fuse_config(fuse_config, :fuse2)
+              res << :nullpath_ok if fuse_config.nullpath_ok?
+            end
+
+            res
+          end
+        end
+
+        # @!visibility private
+        module Fuse3Prepend
+          def init(*args)
+            init_fuse_config(args.detect { |a| a.is_a?(FuseConfig) }) if respond_to?(:init_fuse_config)
+            super if defined?(super)
+          end
+        end
+
+        # @!visibility private
+        def self.included(mod)
+          prepend_module = Libfuse.FUSE_MAJOR_VERSION == 2 ? Fuse2Prepend : Fuse3Prepend
+          mod.prepend(prepend_module)
+        end
+
+        # @!method init_fuse_config(fuse_config,compat)
+        # @abstract
+        # Define this method to configure the fuse config object so that under Fuse2 the config options
+        # can be converted to appropriate flags.
+        #
+        # @param [FuseConfig] fuse_config the fuse config object
+        # @param [Symbol] compat either :fuse2 or :fuse3
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/adapter/fuse3_support.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module FFI
+  module Libfuse
+    module Adapter
+      # Wrapper module to assist filesystem written for Fuse2 to be compatible with Fuse3
+      #
+      # @note there are some deprecated Fuse2 features that have no forwards compatibility in Fuse3
+      #
+      #  - flag nopath became fuse_config.nullpath_ok but it is not compatible since chmod/chown etc will now
+      #    receive a null path but the filesystem cannot receive the new fuse_file_info arg
+      #
+      module Fuse3Support
+        # The actual module methods that are prepended
+        # @!visibility private
+        module Prepend
+          include Adapter
+
+          # Inner adapters received Fuse2 compatible args
+          def fuse3_compat?
+            false
+          end
+
+          def getattr(*args)
+            fi = args.pop
+            return fgetattr(*args, fi) if fi && respond_to?(:fgetattr)
+
+            super(*args)
+          end
+
+          def truncate(*args)
+            fi = args.pop
+            return ftruncate(*args, fi) if fi && respond_to?(:ftruncate)
+
+            super(*args)
+          end
+
+          def chown(*args)
+            args.pop
+            super(*args)
+          end
+
+          def chmod(*args)
+            args.pop
+            super(*args)
+          end
+
+          # TODO: Fuse3 deprecated flag utime_omit_ok - which meant that UTIME_OMIT and UTIME_NOW are passed through
+          #  instead of ????
+          #  Strictly if the flag is not set this compat shim should convert utime now values to Time.now
+          #  but there is no way to handle OMIT
+          def utimens(*args)
+            args.pop
+            super(*args)
+          end
+
+          def init(*args)
+            args.pop
+
+            # TODO: populate FuseConfig with output from fuse_flags/FuseConnInfo where appropriate
+            super(*args)
+          end
+
+          def readdir(*args, &block)
+            # swallow the flag arg unknown to fuse 2
+            args.pop
+
+            args = args.map do |a|
+              next a unless a.is_a?(FFI::Function)
+
+              # wrap the filler proc for the extra flags argument
+              proc { |buf, name, stat, off| a.call(buf, name, stat, off, 0) }
+            end
+
+            super(*args, &block)
+          end
+        end
+
+        # @!visibility private
+        def self.included(mod)
+          # We prepend our shim module so caller doesn't have to call super
+          mod.prepend(Prepend) if FUSE_MAJOR_VERSION > 2
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/adapter/interrupt.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../fuse_context'
+
+module FFI
+  module Libfuse
+    module Adapter
+      # Wrapper module to handle interrupts
+      #
+      # Include this module if you want all requests to check for interruption before processing
+      #
+      # To handle interrupts only for specific callbacks just call {Libfuse.raise_interrupt} or
+      # {Libfuse.fuse_interrupted?} during callback processing rather than including this adapter
+      module Interrupt
+        # @!visibility private
+        def fuse_wrappers(*wrappers)
+          wrappers << {
+            wrapper: proc { |_fuse_method, *args, &b| Interrupt.interrupt_callback(*args, &b) },
+            excludes: %i[init destroy]
+          }
+          return wrappers unless defined?(super)
+
+          super(*wrappers)
+        end
+
+        module_function
+
+        # @raise [Errno::EINTR] if the fuse request is marked as interrupted
+        def interrupt_callback(*args)
+          return -Errno::EINTR::Errno if Libfuse.fuse_interrupted?
+
+          yield(*args)
+        end
+      end
+    end
+  end
+end