rfuse 1.2.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9bbd56ab8bb580e8c2a40b19b15a75bf7afad004296c72d3e8157e0a6fbb223
-  data.tar.gz: 1eeef7cb6a0f6a874da3b87d99452af3737cfa7d973650ccb5eaed992174a48f
+  metadata.gz: a2b3262586963a7807162c2eaa6666d7efe4b0862ad875ff3b7628b34d2fa46a
+  data.tar.gz: 0b5af04342c576f711f4bbced1c2f0e414f137ae35a8706ed7589adc5ba0e741
 SHA512:
-  metadata.gz: 124adc8292a4f1a017e3034d51d645486629992f97ff8b106366929a752b36bf3f25e228001cb8af21a5f7a98147c430bbf2de226d31f7e4392c4bba83151b86
-  data.tar.gz: 11b76dd86a7b1687ef877c6d660a71c041d728341bb5e3200da5a97f6ba80a64102fd2134338f9c7edca67106688ba0a9109fc76024c2fb800254b33f7994d3d
+  metadata.gz: 1c3d4a7afea7a164ef591106ece30900af96777d547ada673bb41b312f45c7eca95bff31f06d5d8052019dc65c03f041cd0a75d822e64419e1063ce912a229dc
+  data.tar.gz: 305ef6632b057dafa8a660f4b1979d4bf892445c644614e97eff2b2b3a94544bf9fb35bf7857bdc073f154d3434aba4bb6d5512e9606b25c5fe2f779e7e5e630

data/.yardopts

@@ -1,4 +1,5 @@
 --no-private
 --markup=markdown
 -
-CHANGES.md
+CHANGELOG.md
+

data/{CHANGES.md → CHANGELOG.md}

@@ -1,3 +1,9 @@
+2.0.0 - 2023/01 UNMAINTAINED
+-------------------
+  * Uses ffi-libfuse instead of local C extension
+  * Starting filesystems through RFuse.main
+  * Require Ruby 2.7+
+
 1.2.0 - 2020/09
 -------------------
   * Fix builds on recent linux

data/README.md

@@ -1,60 +1,32 @@
-RFuse
+RFuse - DEPRECATED
 ===============
 
-http://rubygems.org/gems/rfuse
-![Gem Version](https://badge.fury.io/rb/rfuse.png)
+### DEPRECATED
 
-Ruby FUSE binding
+This gem exists and is maintained for backwards compatibility only.
 
-FUSE (Filesystem in USErspace) is a simple interface for userspace programs to export a virtual filesystem to the linux kernel. FUSE aims to provide a secure method for non privileged users to create and mount their own filesystem implementations.
+Existing RFuse filesystems are recommended to refactor to depend directly on
+[ffi_libfuse](http://rubygems.org/gems/ffi-libfuse) which supports Fuse 3 and Macfuse
 
-This library provides the low-level fuse operations as callbacks into a ruby object.
+{RFuse::Adapter} documents the fuse method signatures that are different to ffi-libfuse
 
-For a more ruby-ish API for creating filesystems see {http://rubygems.org/gems/rfusefs RFuseFS} which is built on RFuse and takes care of some of the heavy lifting.
-
-Dependencies
---------------
-
- * Ruby 2.5+
- * Fuse 2.8+
-
-Installation
 ---------------
 
-    gem install rfuse
-
-Creating a filesystem
----------------------------
-
-Create your filesystem as a class implementing the abstract FUSE methods from {RFuse::Fuse} as necessary.
-
-Run it with {RFuse.main}
+### Dependencies
 
-For a sample filesystem see sample/test-ruby.rb
-
-To run the example:
-
-     mkdir /tmp/fuse
-     ruby sample/test-ruby.rb /tmp/fuse
-
-there should be an empty in-memory filesystem mounted at `/tmp/fuse`
+ * Ruby 2.7+
+ * Fuse 2.8+ / Fuse 3 / MACFuse
 
 HISTORY
-======
-This project is forked from rfuse-ng which was forked from the original rfuse.
+============
+
+This project was forked from rfuse-ng which was forked from the original rfuse.
 
 RFuse-NG: Tamás László Fábián <giganetom@gmail.com> et al on Github
 
 Original Rfuse (@rubyforge): Peter Schrammel AT gmx.de
 
-See also {file:CHANGES.md}
+See also {file:CHANGELOG.md}
 
-CONTRIBUTING
+~~CONTRIBUTING~~
 ============
-
-1. Fork it on {http://github.com/lwoggardner/rfuse on GitHub}
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Write some specs and make them pass
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request

data/lib/rfuse/flock.rb

@@ -0,0 +1,31 @@
+module RFuse
+  # Wrapper for FFI:Flock back to RFuse
+  class Flock
+
+    attr_reader :delegate
+
+    def initialize(ffi_flock)
+      @delegate = ffi_flock
+    end
+
+    def l_type
+      FFI::Flock::Enums::LockType.to_h[delegate.type] || 0
+    end
+
+    def l_whence
+      FFI::Flock::Enums::SeekWhenceShort.to_h[delegate.whence] || 0
+    end
+
+    def l_start
+      delegate.start
+    end
+
+    def l_len
+      delegate.len
+    end
+
+    def l_pid
+      delegate.pid
+    end
+  end
+end

data/lib/rfuse/gem_version.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+begin
+  require 'ffi/libfuse/gem_helper'
+rescue LoadError
+  # allow bundle install to run
+end
+
+module RFuse
+  # @!visibility private
+  MAIN_BRANCH = 'master'
+  GEM_VERSION, =
+    if defined? FFI::Libfuse
+      FFI::Libfuse::GemHelper.gem_version(version: VERSION, main_branch: MAIN_BRANCH)
+    else
+      "#{VERSION}.pre"
+    end
+end
+

data/lib/rfuse/rfuse.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require 'ffi/libfuse'
+
+module RFuse
+  # Filler object
+  # @see readdir
+  class Filler < FFI::Libfuse::Adapter::Ruby::ReaddirFiller
+
+    def push(name, stat, offset = 0)
+      fill(name, stat: stat, offset: offset)
+    end
+  end
+
+  # Map callback methods to be compatible for legacy RFuse
+  #
+  # All native {FuseOperations} callback signatures are amended to take {FuseContext} as the first argument.
+  #
+  # A subset of callbacks are documented here where their signatures are further altered to match RFuse
+  #
+  # RFuse did not support Fuse3
+  # adapter module
+  module Adapter
+
+    # Converts Fuse2 calls into RFuse calls
+    # @!visibility private
+    module Prepend
+
+      include FFI::Libfuse::Adapter
+
+      def readdir(ctx, path, buf, filler, offset, ffi)
+
+        rd_filler = Filler.new(buf, filler, fuse3: false)
+        super(ctx, path, rd_filler, offset, ffi)
+        0
+      end
+
+      def readlink(ctx, path, buf, size)
+        link = super(ctx, path)
+
+        return -Errno::ERANGE::Errno unless link.size <= size
+
+        buf.write_bytes(link)
+        0
+      end
+
+      def mknod(ctx, path, mode, dev)
+        super(ctx, path, mode, FFI::Device.major(dev), FFI::Device.minor(dev))
+        0
+      end
+
+      def getattr(ctx, path, stat_buf)
+        result = super(ctx, path)
+        raise Errno::ENOENT unless result
+
+        stat_buf.fill(result)
+        0
+      end
+
+      def fgetattr(ctx, path, stat_buf, ffi)
+        stat_buf.fill(super(ctx, path, ffi))
+        0
+      end
+
+      # Set file atime, mtime via super as per {Ruby#utimens}
+      def utimens(ctx, path, times)
+        atime, mtime = Stat::TimeSpec.fill_times(times[0, 2], 2)
+
+        begin
+          super(ctx, path, atime.nanos, mtime.nanos)
+        rescue NoMethodError
+          utime(ctx, path, atime.sec, mtime.sec)
+        end
+        0
+      end
+
+      def read(ctx, path, buf, size, offset, info)
+        res = super(ctx, path, size, offset, info)
+
+        return -Errno::ERANGE::Errno unless res.size <= size
+
+        buf.write_bytes(res)
+        res.size
+      end
+
+      def write(ctx, path, buf, size, offset, info)
+        super(ctx, path, buf.read_bytes(size), offset, info)
+      end
+
+      def statfs(ctx, path, statfs_buf)
+        statfs_buf.fill(super(ctx, path))
+        0
+      end
+
+      def setxattr(ctx, path, name, value, _size, flags)
+        super(ctx, path, name, value, FFI::Libfuse::XAttr.to_h[flags] || 0)
+        0
+      end
+
+      def getxattr(ctx, path, name, buf, size)
+        FFI::Libfuse::Adapter::Ruby.getxattr(buf, size) do
+          super(ctx, path, name)
+        end
+      end
+
+      def listxattr(ctx, path, buf, size)
+        FFI::Libfuse::Adapter::Ruby.listxattr(buf, size) do
+          super(ctx, path)
+        end
+      end
+
+      %i[create open opendir].each do |fuse_method|
+        define_method(fuse_method) do |*args|
+          super(*args)
+          store_handle(args.last&.fh)
+          0
+        end
+      end
+
+      %i[release releasedir].each do |fuse_method|
+        define_method(fuse_method) do |*args|
+          super(*args)
+          0
+        rescue NoMethodError
+          # OK, just release the file handle
+          0
+        ensure
+          release_handle(args.last&.fh)
+        end
+      end
+
+      def init(ctx, fuse_conn_info)
+        super
+        self
+      end
+
+      def lock(ctx, path, ffi, cmd, lock)
+        super(ctx, path, ffi, FFI::Flock::Enums::LockCmd.to_h[cmd], Flock.new(lock))
+        0
+      end
+
+      def fuse_respond_to?(fuse_callback)
+        return true if super
+
+        case fuse_callback
+        when :release
+          # Ensure file handles to be cleaned up at release
+          %i[open create].any? { |m| super(m) }
+        when :release_dir
+          super(:open_dir)
+        when :utimens
+          super(:utime)
+        else
+          false
+        end
+      end
+
+      def open_files
+        handles
+      end
+
+      private
+
+      # Prevent filehandles from being GCd
+      def handles
+        @handles ||= Set.new.compare_by_identity
+      end
+
+      def store_handle(file_handle)
+        handles << file_handle if file_handle
+      end
+
+      def release_handle(file_handle)
+        handles.delete(file_handle)
+      end
+    end
+
+
+    # @!method readdir(context,path,filler,offset,ffi)
+    #
+    #  List contents of a directory
+    #
+    #  @param [Context] context
+    #  @param [String] path
+    #  @param [Filler] filler
+    #  @param [Fixnum] offset
+    #  @param [FileInfo] ffi
+    #
+    #  @return [void]
+    #  @raise [Errno]
+
+    # @!method readlink(path)
+    #  @abstract
+    #  @param [String] path
+    #  @return [String] the link target
+
+    # @!method mknod(context,path,mode,major,minor)
+    # Create a file node
+    #    @abstract Fuse Operation {http://fuse.sourceforge.net/doxygen/structfuse__operations.html#1465eb2268cec2bb5ed11cb09bbda42f mknod}
+    #
+    #    @param [Context] context
+    #    @param [String] path
+    #    @param [Integer] mode  type & permissions
+    #    @param [Integer] major
+    #    @param [Integer] minor
+    #
+    #    @return[void]
+    #
+    #    This is called for creation of all non-directory, non-symlink nodes. If the filesystem defines {#create}, then for regular files that will be called instead.
+
+    # @!method getattr(ctx,path)
+    #  @param [FuseContext ctx]
+    #  @param [String] path
+    #  @return [Stat] the stat information (or something that can fill a stat)
+
+    # @!method fgetattr(ctx,path,ffi)
+    #  @param [FuseContext ctx]
+    #  @param [String] path
+    #  @return [Stat] the stat information (or something that can fill a stat)
+
+    # @!method utime(ctx,path,atime,mtime)
+    #  @abstract
+    #  @deprecated prefer {utimens}
+    #
+    #  @param [Context] context
+    #  @param [String] path
+    #  @param [Integer] atime access time in seconds or nil if only setting mtime
+    #  @param [Integer] mtime modification time in seconds or nil if only setting atime
+    #
+    #  @return [void]
+    #  @raise [Errno]
+
+    # @!method utimens(ctx,path,atime,mtime)
+    #  @abstract
+    #  @param [Context] context
+    #  @param [String] path
+    #  @param [Integer] atime access time in nanoseconds or nil if only setting mtime
+    #  @param [Integer] mtime modification time in nanoseconds or nil if only setting atime
+    #
+    #  @return [void]
+    #  @raise [Errno]
+
+    # @!method read(ctx,path,size,offset,info)
+    #  @abstract
+    #  @param [FuseContext ctx]
+    #  @param [String] path
+    #  @param [Integer] size
+    #  @param [Integer] offset
+    #  @param [FuseFileInfo] info
+    #
+    #  @return [String] the data, expected to be exactly size bytes
+
+    # @!method write(ctx,path,data,offset,info)
+    #    @abstract Fuse operation {http://fuse.sourceforge.net/doxygen/structfuse__operations.html#897d1ece4b8b04c92d97b97b2dbf9768 write}
+    #    Write data to an open file
+    #
+    #    @param [Context] context
+    #    @param [String] path
+    #    @param [String] data
+    #    @param [Integer] offset
+    #    @param [FileInfo] ffi
+    #
+    #    @return [Integer] exactly the number of bytes requested except on error
+    #    @raise [Errno]
+
+    #    Set extended attributes
+    #
+    #    @!method setxattr(context,path,name,data,flags)
+    #    @abstract Fuse operation {http://fuse.sourceforge.net/doxygen/structfuse__operations.html#988ced7091c2821daa208e6c96d8b598 setxattr}
+    #    @param [Context] context
+    #    @param [String] path
+    #    @param [String] name
+    #    @param [String] data
+    #    @param [Integer] flags
+    #
+    #    @return [void]
+    #    @raise [Errno]
+
+    # @method getxattr(ctx,path,name)
+    #  @abstract
+    #  @param [FuseContext ctx]
+    #  @param [String] path
+    #  @param [String] name the attribute name
+    #  @return [String|nil] the attribute value or nil if it does not exist
+
+    # @method listxattr(ctx,path)
+    #  @abstract
+    #  @param [FuseContext ctx]
+    #  @param [String] path
+    #  @return [Array<String>] list of attribute names for path
+
+    # @!visibility private
+
+    def fuse_wrappers(*wrappers)
+      # Change signatures to match legacy RFuse
+      wrappers.unshift({
+        wrapper: proc { |_fm, *args, &b|  b.call(FFI::Libfuse::FuseContext.get, *args) },
+        excludes: %i[destroy]
+      })
+
+      return wrappers unless defined?(super)
+
+      super(*wrappers)
+    end
+
+    def default_errno
+      Errno::ENOENT::Errno
+    end
+
+    def self.included(mod)
+      mod.prepend(Prepend)
+      mod.include(FFI::Libfuse::Adapter::Fuse3Support)
+      mod.include(FFI::Libfuse::Adapter::Safe)
+    end
+
+  end
+end
+

data/lib/rfuse/stat.rb

@@ -0,0 +1,43 @@
+module RFuse
+  # Helper class to return from :getattr method
+  class Stat
+
+    # See FFI::Stat constants
+    def self.const_missing(const)
+      return super unless FFI::Stat.const_defined?(const)
+      FFI::Stat.const_get(const)
+    end
+
+    # @param [Fixnum] mode file permissions
+    # @param [Hash<Symbol,Fixnum>] values initial values for other attributes
+    #
+    # @return [Stat] representing a directory
+    def self.directory(mode = 0, values = {})
+      new(S_IFDIR, mode, values)
+    end
+
+    # @param [Fixnum] mode file permissions
+    # @param [Hash<Symbol,Fixnum>] values initial values for other attributes
+    #
+    # @return [Stat] representing a regular file
+    def self.file(mode = 0, values = {})
+      new(S_IFREG, mode, values)
+    end
+
+    # @return [Integer] see stat(2)
+    attr_accessor :uid, :gid, :mode, :size, :dev, :ino, :nlink, :rdev, :blksize, :blocks
+
+    # @return [Integer, Time] see stat(2)
+    attr_accessor :atime, :mtime, :ctime
+
+    def initialize(type, permissions, values = {})
+      values[:mode] = ((type & S_IFMT) | (permissions & 0o7777))
+      @uid, @gid, @size, @mode, @atime, @mtime, @ctime, @dev, @ino, @nlink, @rdev, @blksize, @blocks = Array.new(
+        13, 0
+      )
+      values.each_pair do |k, v|
+        instance_variable_set("@#{k}", v)
+      end
+    end
+  end
+end

data/lib/rfuse/statvfs.rb

@@ -0,0 +1,33 @@
+module RFuse
+
+  # Helper class to return from :statfs (eg for df output)
+  # All attributes are Integers and default to 0
+  class StatVfs
+    # @return [Integer]
+    attr_accessor :f_bsize, :f_frsize, :f_blocks, :f_bfree, :f_bavail
+
+    # @return [Integer]
+    attr_accessor :f_files, :f_ffree, :f_favail, :f_fsid, :f_flag, :f_namemax
+
+    # values can be symbols or strings but drop the pointless f_ prefix
+    def initialize(values = {})
+      @f_bsize, @f_frsize, @f_blocks, @f_bfree, @f_bavail, @f_files, @f_ffree, @f_favail, @f_fsid, @f_flag, @f_namemax = Array.new(
+        13, 0
+      )
+      values.each_pair do |k, v|
+        prefix = k.to_s.start_with?('f_') ? '' : 'f_'
+        instance_variable_set("@#{prefix}#{k}", v)
+      end
+    end
+
+    def respond_to_missing?(method, private=false)
+      !method.start_with?('f_') && respond_to?("f_#{method}", private)
+    end
+
+    def method_missing(method, *args)
+      return super if method.start_with?('f_')
+
+      send("f_#{method}", *args)
+    end
+  end
+end

data/lib/rfuse/version.rb

@@ -1,3 +1,3 @@
 module RFuse
-  VERSION = "1.2.3"
+  VERSION = "2.0.0"
 end