ffi-libfuse 0.0.1.pre → 0.1.0.rc20220550

data/lib/ffi/libfuse/filesystem/virtual_dir.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require_relative 'accounting'
+require_relative 'virtual_node'
+require_relative 'virtual_file'
+require_relative 'pass_through_file'
+require_relative 'pass_through_dir'
+require_relative 'mapped_dir'
+
+module FFI
+  module Libfuse
+    module Filesystem
+      # A Filesystem of Filesystems
+      #
+      # Implements a recursive Hash based directory of sub filesystems.
+      #
+      # FUSE Callbacks
+      # ===
+      #
+      # If path is root ('/') then the operation applies to this directory itself
+      #
+      # If the path is a simple basename (with leading slash and no others) then the operation applies to an entry in
+      #  this directory.  The operation is handled by the directory and then passed on to the entry itself
+      #  (with path = '/')
+      #
+      # Otherwise it is passed on to the next entry via {#path_method}
+      #
+      # Constraints
+      # ===
+      #
+      #   * Expects to be wrapped by {Adapter::Safe}
+      #   * Passes on FUSE Callbacks to sub filesystems agnostic of {FUSE_MAJOR_VERSION}. Sub-filesystems should use
+      #     {Adapter::Fuse2Compat} or {Adapter::Fuse3Support} as required
+      #
+      class VirtualDir < VirtualNode
+        include Utils
+
+        # @return [Hash<String,FuseOperations>] our directory entries
+        attr_reader :entries
+
+        def initialize(accounting: Accounting.new)
+          @entries = {}
+          @mounted = false
+          super(accounting: accounting)
+        end
+
+        # @return [Boolean] true if this dir been mounted
+        def mounted?
+          @mounted
+        end
+
+        # @!endgroup
+
+        # @!group FUSE Callbacks
+
+        # For the root path provides this directory's stat information, otherwise passes on to the next filesystem
+        def getattr(path, stat_buf = nil, _ffi = nil)
+          return path_method(__method__, path, stat_buf) unless root?(path)
+
+          stat_buf&.directory(**virtual_stat.merge({ nlink: entries.size + 2 }))
+        end
+
+        # Safely passes on file open to next filesystem
+        #
+        # @raise [Errno::EISDIR] for the root path since we are a directory rather than a file
+        # @return [Object] the result of {#path_method} for the sub filesystem
+        # @return [nil] for sub-filesystems that do not implement this callback or raise ENOTSUP or ENOSYS
+        def open(path, *args)
+          raise Errno::EISDIR if root?(path)
+
+          path_method(__method__, path, *args, notsup: nil)
+        rescue Errno::ENOTSUP, Errno::ENOSYS
+          nil
+        end
+
+        # Safely handle file release
+        #
+        # Passes on to next filesystem, rescuing ENOTSUP or ENOSYS
+        # @raise [Errno::EISDIR] for the root path since we are a directory rather than a file
+        def release(path, *args)
+          raise Errno::EISDIR if root?(path)
+
+          path_method(__method__, path, *args, notsup: nil)
+        rescue Errno::ENOTSUP, Errno::ENOSYS
+          # do nothing
+        end
+
+        # Safely handles directory open to next filesystem
+        #
+        # @return [self] for the root path, which helps shortcut future operations. See {#readdir}
+        # @return [Object] the result of {#path_method} for all other paths
+        # @return [nil] for sub-filesystems that do not implement this callback or raise ENOTSUP or ENOSYS
+        def opendir(path, ffi)
+          return path_method(__method__, path, ffi, notsup: nil) unless root?(path)
+
+          ffi.fh = self
+        rescue Errno::ENOTSUP, Errno::ENOSYS
+          nil
+        end
+
+        # Safely handles directory release
+        #
+        # Does nothing for the root path
+        #
+        # Otherwise safely passes on to next filesystem, rescuing ENOTSUP or ENOSYS
+        def releasedir(path, *args)
+          path_method(__method__, path, *args, notsup: nil) unless root?(path)
+        rescue Errno::ENOTSUP, Errno::ENOSYS
+          # do nothing
+        end
+
+        # If path is root fills the directory from the keys in {#entries}
+        #
+        # If ffi.fh is itself a filesystem then try to call its :readdir directly
+        #
+        # Otherwise passes to the next filesystem in path
+        def readdir(path, buf, filler, offset, ffi, *flag)
+          return %w[. ..].concat(entries.keys).each(&Adapter::Ruby::ReaddirFiller.new(buf, filler)) if root?(path)
+
+          return ffi.fh.readdir('/', buf, filler, offset, ffi, *flag) if entry_fuse_respond_to?(ffi.fh, :readdir)
+
+          path_method(:readdir, path, buf, filler, offset, ffi, *flag) unless root?(path)
+        end
+
+        # For root path validates we are empty and removes a node link from {#accounting}
+        # For our entries, passes on the call to the entry (with path='/') and then removes the entry. If available
+        #  :destroy will be called on the deleted entry
+        # @raise [Errno::ENOTEMPTY] if path is root and our entries list is not empty
+        # @raise [Errno::ENOENT] if the entry does not exist
+        # @raise [Errno::ENOTDIR] if the entry does not respond to :readdir (ie: is not a directory)
+        def rmdir(path)
+          if root?(path)
+            raise Errno::ENOTEMPTY unless entries.empty?
+
+            accounting.adjust(0, -1)
+            return
+          end
+
+          entry_key = entry_key(path)
+          return path_method(__method__, path) unless entry_key
+
+          dir = entries[entry_key]
+          raise Errno::ENOENT unless dir
+          raise Errno::ENOTDIR unless entry_fuse_respond_to?(dir, :readdir)
+
+          entry_send(dir, :rmdir, '/')
+
+          dir = entries.delete(entry_key)
+          entry_send(dir, :destroy, init_results.delete(entry_key)) if dir && mounted?
+        end
+
+        # For our entries, validates the entry exists and is not a directory, then passes on unlink (with path = '/')
+        #  and finally deletes.
+        # @raise [Errno:EISDIR] if the request entry responds to :readdir
+        def unlink(path)
+          entry_key = entry_key(path)
+          return path_method(__method__, path) unless entry_key
+
+          entry = entries[entry_key]
+          raise Errno::ENOENT unless entry
+          raise Errno::EISDIR if entry_fuse_respond_to?(entry, :readdir)
+
+          entry_send(entry, :unlink, '/')
+          entries.delete(entry_key) && true
+        end
+
+        # For our entries, creates a new file
+        # @raise [Errno::EISDIR] if the entry exists and responds_to?(:readdir)
+        # @raise [Errno::EEXIST] if the entry exists
+        # @yield []
+        # @yieldreturn [Object] something that quacks with the FUSE Callbacks of a regular file
+        #
+        #   :create or :mknod + :open will be attempted with path = '/' on this file
+        # @return [Object] the result of the supplied block, or if not given a new {VirtualFile}
+        def create(path, mode = FuseContext.get.mask(0o644), ffi = nil, &file)
+          file_name = entry_key(path)
+
+          # fuselib will fallback to mknod on ENOSYS on a case by case basis
+          return path_method(__method__, path, mode, ffi, notsup: Errno::ENOSYS, &file) unless file_name
+
+          existing = entries[file_name]
+          raise Errno::EISDIR if entry_fuse_respond_to?(existing, :readdir)
+          raise Errno::EEXIST if existing
+
+          # TODO: Strictly should understand setgid and sticky bits of this dir's mode when creating new files
+          new_file = file ? file.call(name) : VirtualFile.new(accounting: accounting)
+          if entry_fuse_respond_to?(new_file, :create)
+            new_file.public_send(:create, '/', mode, ffi)
+          else
+            # TODO: generate a sensible device number
+            entry_send(new_file, :mknod, '/', mode, 0)
+            entry_send(new_file, :open, '/', ffi)
+          end
+          entries[file_name] = new_file
+        end
+
+        # Creates a new directory entry in this directory
+        # @param [String] path
+        # @param [Integer] mode
+        # @yield []
+        # @yieldreturn [Object] something that quacks with the FUSE Callbacks representing a directory
+        # @return [Object] the result of the block if given, otherwise the newly created sub {VirtualDir}
+        # @raise [Errno::EEXIST] if the entry already exists at path
+        def mkdir(path, mode = FuseContext.get.mask(0o777), &dir)
+          return init_node(mode) if root?(path)
+
+          dir_name = entry_key(path)
+          return path_method(__method__, path, mode, &dir) unless dir_name
+
+          existing = entries[dir_name]
+          raise Errno::EEXIST if existing
+
+          new_dir = dir ? dir.call : VirtualDir.new(accounting: accounting)
+          init_dir(dir_name, new_dir) if mounted?
+          entry_send(new_dir, :mkdir, '/', mode)
+          entries[dir_name] = new_dir
+        end
+
+        # Calls init on all current entries, keeping track of their init objects for use with {destroy}
+        def init(*args)
+          @mounted = true
+          @init_args = args
+          @init_results = {}
+          entries.each_pair { |name, d| init_dir(name, d) }
+          nil
+        end
+
+        # Calls destroy on all current entries
+        def destroy(*_args)
+          entries.each_pair { |name, d| entry_send(d, :destroy, init_results[name]) }
+          nil
+        end
+
+        # @!endgroup
+
+        # Looks up the first path component in {#entries} and then sends the remainder of the path to the callback
+        # on that entry
+        # @param [Symbol] callback a FUSE Callback
+        # @param [String] path
+        # @param [Array] args callback arguments
+        # @param [Proc] invoke optional block to keep passing down. See {#mkdir}, {#create}
+        # @param [Class<SystemCallError>] notsup
+        # @raise [Errno:ENOENT] if the next entry does not exist
+        # @raise [SystemCallError] error from notsup if the next entry does not respond to ths callback
+        def path_method(callback, path, *args, notsup: Errno::ENOTSUP, &invoke)
+          path = path.to_s
+          # Fuse paths always start with a leading slash and never have a trailing slash
+          sep_index = path.index('/', 1)
+          entry_key = sep_index ? path[1..sep_index - 1] : path[1..]
+          entry = entries[entry_key]
+
+          raise Errno::ENOENT unless entry
+
+          responds = entry_fuse_respond_to?(entry, callback)
+          return unless responds || notsup
+          raise notsup unless responds
+
+          if mounted? && (init_obj = init_results[entry_key])
+            FuseContext.get.overrides.merge!(private_data: init_obj)
+          end
+
+          # Pass remaining path components to the next filesystem
+          next_path = sep_index ? path[sep_index..] : '/'
+          entry.public_send(callback, next_path, *args, &invoke)
+        end
+
+        private
+
+        attr_reader :init_args, :init_results
+
+        def method_missing(method, *args, &invoke)
+          return super unless FuseOperations.path_callbacks.include?(method)
+
+          raise Errno::ENOTSUP if root?(args.first)
+
+          path_method(method, *args, &invoke)
+        end
+
+        def respond_to_missing?(method, inc_private = false)
+          return true if FuseOperations.path_callbacks.include?(method)
+
+          super
+        end
+
+        def entry_key(path)
+          path[1..] unless path.index('/', 1)
+        end
+
+        def init_dir(name, dir)
+          init_result = entry_fuse_respond_to?(dir, :init) ? dir.init(*init_args) : nil
+          init_results[name] = init_result if init_result
+        end
+
+        def entry_fuse_respond_to?(entry_fs, method)
+          entry_fs.respond_to?(:fuse_respond_to?) ? entry_fs.fuse_respond_to?(method) : entry_fs.respond_to?(method)
+        end
+
+        def entry_send(entry, callback, *args)
+          return unless entry_fuse_respond_to?(entry, callback)
+
+          entry.public_send(callback, *args)
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/filesystem/virtual_file.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'accounting'
+require 'stringio'
+
+module FFI
+  module Libfuse
+    module Filesystem
+      # A Filesystem representing a single synthetic file at the root
+      class VirtualFile < VirtualNode
+        prepend Adapter::Ruby::Prepend
+        include Fuse2Compat
+
+        # @return [String] the (binary) content of the synthetic file
+        attr_reader :content
+
+        # Create an empty synthetic file
+        def initialize(accounting: nil)
+          super(accounting: accounting)
+        end
+
+        # @!visibility private
+        def path_method(_method, *_args)
+          raise Errno::ENOENT
+        end
+
+        # @!group FUSE Callbacks
+
+        def getattr(path, stat, ffi = nil)
+          # We don't exist until create or otherwise or virtual stat exists
+          raise Errno::ENOENT unless root?(path) && virtual_stat
+
+          stat.file(size: (ffi&.fh || content).size, **virtual_stat)
+          self
+        end
+
+        # @param [String] _path ignored, expected to be '/'
+        # @param [Integer] mode
+        # @param [FuseFileInfo] ffi
+        # @return [Object] a file handled (captured by {Adapter::Ruby::Prepend})
+        def create(_path, mode, ffi = nil)
+          init_node(mode)
+          @content = String.new(encoding: 'binary')
+          sio(ffi) if ffi
+        end
+
+        def open(_path, ffi)
+          virtual_stat[:atime] = Time.now.utc
+          sio(ffi)
+        end
+
+        # op[:read] = [:pointer, :size_t, :off_t, FuseFileInfo.by_ref]
+        def read(path, size, off, ffi)
+          raise Errno::ENOENT unless root?(path)
+
+          io = sio(ffi)
+          io.seek(off)
+          io.read(size)
+        end
+
+        # write(const char* path, char *buf, size_t size, off_t offset, struct fuse_file_info* fi)
+        def write(path, data, offset = 0, ffi = nil)
+          raise Errno::ENOENT unless root?(path)
+
+          accounting&.write(content.size, data.size, offset)
+          io = sio(ffi)
+          io.seek(offset)
+          io.write(data)
+          virtual_stat[:mtime] = Time.now.utc
+        end
+
+        def truncate(path, size, ffi = nil)
+          raise Errno::ENOENT unless root?(path)
+
+          accounting&.truncate(content.size, size)
+          sio(ffi).truncate(size)
+          virtual_stat[:mtime] = Time.now.utc
+        end
+
+        def unlink(path)
+          raise Errno::ENOENT unless root?(path)
+
+          accounting&.adjust(-content.size, -1)
+        end
+
+        private
+
+        def sio(ffi)
+          ffi&.fh || StringIO.new(content, ffi&.flags)
+        end
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/filesystem/virtual_fs.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+require_relative 'virtual_dir'
+require_relative 'accounting'
+require 'pathname'
+
+module FFI
+  module Libfuse
+    module Filesystem
+      # A configurable main Filesystem that delegates FUSE Callbacks to another filesystem
+      #
+      # This class registers support for all available fuse callbacks, subject to the options below.
+      #
+      # Delegate filesystems like {VirtualDir} may raise ENOTSUP to indicate a callback is not handled at runtime
+      #   although the behaviour of C libfuse varies in this regard.
+      #
+      # Filesystem options
+      # ===
+      #
+      # Passed by -o options to {Libfuse.main}
+      #
+      #   * :max_space used for #{FuseOperations#statfs}. See {#accounting}
+      #   * :max_nodes used for #{FuseOperations#statfs}. See {#accounting}
+      #   * :no_buf do not register :read_buf, :write_buf
+      #
+      #       when set all filesystems must implement :read/:write
+      #
+      #       when not set all filesystems must implement :read_buf, :write_buf which enables C libfuse to handle
+      #       file descriptor based io, eg. {MappedFiles}, but means Ruby FFI is doing memory allocations for string
+      #       based io, eg. {VirtualFile}.
+      #
+      #       Note that {VirtualFile} and {MappedFiles} both prepend {Adapter::Ruby::Prepend} which implements
+      #       the logic to fallback from :read/:write_buf to plain :read/:write as necessary to support this option.
+      #
+      # It is writable to the user that mounted it may create and edit files within it
+      #
+      # @example
+      #   class MyFS < FFI::Libfuse::Filesystem::VirtualFS
+      #     def fuse_configure
+      #       build({ 'hello' => { 'world.txt' => 'Hello World'}})
+      #       mkdir("/hello")
+      #       create("/hello/world").write("Hello World!\n")
+      #       create("/hello/everybody").write("Hello Everyone!\n")
+      #     end
+      #   end
+      #
+      #   exit(FFI::Libfuse.fuse_main(operations: MyFS.new))
+      #
+      class VirtualFS
+        include Utils
+        include Adapter::Context
+        include Adapter::Debug
+        include Adapter::Safe
+
+        # @return [Object] the root filesystem that quacks like a {FuseOperations}
+        attr_reader :root
+
+        # @return [Hash{Symbol => String,Boolean}] custom options captured as defined by {fuse_options}
+        attr_reader :options
+
+        # @return [Accounting|:max_space=,:max_nodes=] an accumulator of filesystem statistics used to consume the
+        #  max_space and max_nodes options
+        def accounting
+          @accounting ||= Accounting.new
+        end
+
+        # @param [FuseOperations] root the root filesystem
+        # Subclasses can override the no-arg method and call super to pass in a different root.
+        def fuse_configure(root = VirtualDir.new(accounting: accounting).mkdir('/'))
+          @root = root
+        end
+
+        # @overload build(files)
+        #  Adds files directly to the filesystem
+        #  @param [Hash] files map of paths to content responding to
+        #
+        #    * :each_pair is treated as a subdir of files
+        #    * :readdir (eg {PassThroughDir}) is treated as a directory- sent via mkdir
+        #    * :getattr (eg {PassThroughFile}) is treated as a file - sent via create
+        #    * :to_str (eg {::String} ) is created as a {VirtualFile}
+        def build(files, base_path = Pathname.new('/'))
+          files.each_pair do |path, content|
+            path = (base_path + path).cleanpath
+            @root.mkdir_p(path.dirname) unless path.dirname == base_path
+
+            rt = %i[each_pair readdir getattr to_str].detect { |m| content.respond_to?(m) }
+            raise "Unsupported initial content for #{self.class.name}: #{content.class.name}- #{content}" unless rt
+
+            send("build_#{rt}", content, path)
+          end
+        end
+
+        # @!group Fuse Configuration
+
+        # TODO: Raise bug on libfuse (or fuse kernel module - ouch!) create to also fallback to mknod on ENOTSUP
+
+        # Respond to all FUSE Callbacks except deprecated, noting that ..
+        #
+        #   * :read_buf, :write_buf can be excluded by the 'no_buf' mount option
+        #   * :access already has a libfuse mount option (default_permissions)
+        #   * :create falls back to :mknod on ENOSYS (as raised by {VirtualDir})
+        #   * :copy_file_range can raise ENOTSUP to trigger glibc to fallback to inefficient copy
+        def fuse_respond_to?(method)
+          case method
+          when :getdir, :fgetattr
+            # TODO: Find out if fgetattr works on linux, something wrong with stat values on OSX.
+            #     https://github.com/osxfuse/osxfuse/issues/887
+            false
+          when :read_buf, :write_buf
+            !no_buf
+          else
+            true
+          end
+        end
+
+        # Default fuse options
+        # Subclasses can override this method and call super with the additional options:
+        # @param [Hash] opts additional options to parse into the {#options} attribute
+        def fuse_options(args, opts = {})
+          @options = {}
+          opts = opts.merge({ 'no_buf' => :no_buf }).merge(Accounting::OPTIONS)
+          args.parse!(opts) do |key:, value:, **|
+            case key
+            when *Accounting::OPTIONS.values.uniq
+              next accounting.fuse_opt_proc(key: key, value: value)
+            when :no_buf
+              @no_buf = true
+            else
+              options[key] = value
+            end
+            :handled
+          end
+        end
+
+        # Subclasses can override this method to add descriptions for additional options
+        def fuse_help
+          <<~END_HELP
+            #{Accounting::HELP}
+            #{self.class.name} options:
+                -o no_buf              always use read, write instead of read_buf, write_buf
+          END_HELP
+        end
+
+        # Subclasses can override to produce a nice version string for -V
+        def fuse_version
+          self.class.name
+        end
+
+        # @!endgroup
+
+        private
+
+        def build_each_pair(content, path)
+          build(content, path)
+        end
+
+        def build_readdir(content, path)
+          @root.mkdir(path.to_s) { content }
+        end
+
+        def build_getattr(content, path)
+          @root.create(path.to_s) { content }
+        end
+
+        def build_to_str(content, path)
+          @root.create(path.to_s) { content }
+        end
+
+        # Passes FUSE Callbacks on to the {#root} filesystem
+        def method_missing(method, *args, &block)
+          return @root.public_send(method, *args, &block) if @root.respond_to?(method)
+
+          # This is not always reliable but better than raising NoMethodError
+          return -Errno::ENOTSUP::Errno if FuseOperations.fuse_callbacks.include?(method)
+
+          super
+        end
+
+        def respond_to_missing?(method, private = false)
+          FuseOperations.fuse_callbacks.include?(method) || @root.respond_to?(method, private) || super
+        end
+
+        attr_reader :no_buf
+      end
+    end
+  end
+end

data/lib/ffi/libfuse/filesystem/virtual_node.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'accounting'
+require_relative '../adapter/ruby'
+
+module FFI
+  module Libfuse
+    module Filesystem
+      # @abstract
+      # Common FUSE Callbacks for a virtual inode
+      #
+      # **Note** this class is used by both {VirtualFile} which is under {Adapter::Ruby::Prepend}
+      #  and {VirtualDir} which passes on native {FuseOperations} calls
+      class VirtualNode
+        # @return [Hash<Symbol,Integer>] base file or directory stat information used for :getattr of this node
+        attr_reader :virtual_stat
+
+        # @return [Hash<String,String>] virtual extended attributes
+        attr_reader :virtual_xattr
+
+        # @return [Accounting|nil] file system statistcs accumulator
+        attr_reader :accounting
+
+        # @param [Accounting] accounting accumulator of filesystem statistics
+        def initialize(accounting: Accounting.new)
+          @accounting = accounting
+
+          @virtual_xattr = {}
+        end
+
+        # @!method path_method(callback, *args)
+        #   @abstract
+        #   called if this node cannot handle the callback (ie path is not root or an entry in this directory)
+
+        # @!group FUSE Callbacks
+
+        def utimens(path, *args)
+          return path_method(__method__, path, *args) unless root?(path)
+
+          atime, mtime, *_fuse3 = args
+          # if native fuse call atime will be Array<Stat::TimeSpec>
+          atime, mtime = Stat::TimeSpec.fill_times(atime[0, 2], 2).map(&:time) if atime.is_a?(Array)
+          virtual_stat[:atime] = atime if atime
+          virtual_stat[:mtime] = mtime if mtime
+          virtual_stat[:ctime] = mtime if mtime
+        end
+
+        def chmod(path, mode, *args)
+          return path_method(__method__, path, mode, *args) unless root?(path)
+
+          virtual_stat[:mode] = mode
+          virtual_stat[:ctime] = Time.now
+        end
+
+        def chown(path, uid, gid, *args)
+          return path_method(__method__, path, uid, gid, *args) unless root?(path)
+
+          virtual_stat[:uid] = uid
+          virtual_stat[:gid] = gid
+          virtual_stat[:ctime] = Time.now
+        end
+
+        def statfs(path, statfs_buf)
+          return path_method(__method__, path, statfs_buf) unless root?(path)
+          raise Errno::ENOTSUP unless accounting
+
+          accounting.to_statvfs(statfs_buf)
+        end
+
+        def getxattr(path, name, buf = nil, size = nil)
+          return path_method(__method__, path, name, buf, size) unless root?(path)
+          return virtual_xattr[name] unless buf
+
+          Adapter::Ruby.getxattr(buf, size) { virtual_xattr[name] }
+        end
+
+        def listxattr(path, buf = nil, size = nil)
+          return path_method(__method__, path) unless root?(path)
+          return virtual_xattr.keys unless buf
+
+          Adapter::Ruby.listxattr(buf, size) { virtual_xattr.keys }
+        end
+
+        # @!endgroup
+
+        # Initialise the stat information for the node - should only be called once (eg from create or mkdir)
+        def init_node(mode, ctx: FuseContext.get, now: Time.now)
+          @virtual_stat = { mode: mode & ~ctx.umask, uid: ctx.uid, gid: ctx.gid, ctime: now, mtime: now, atime: now }
+          accounting&.adjust(0, +1)
+          self
+        end
+
+        private
+
+        def root?(path)
+          path.to_s == '/'
+        end
+      end
+    end
+  end
+end