ffi-libfuse 0.0.1.rctest12 → 0.1.0.rc20220550

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cc15469bfd68dbe59e7b5dfab82fc1b34fe51e7e3b61e44c686d8a8025ec5ff
-  data.tar.gz: 691758dbb28272d60cfc1f5f2f37e8cef56de15412706b303f181c5b31cdf03f
+  metadata.gz: d71e73d4261d20d3e8318fa01517342da232c0167f4febd73249fb99bb314e15
+  data.tar.gz: 5d478d73897b3d590b1c23ddc656f416574865a53db88bb078ddc949c310bc81
 SHA512:
-  metadata.gz: 6dfefe8f3a512dcaa6f2ca34c3f45cba0fb61e17af4dc0114b9fec6a1adc7a63b0f156415b69e256b9bae97d5a9574626001e285f85ddaae985df84d840b2ca3
-  data.tar.gz: cb4d1f15b5220c9ec4c16a2c0874c082b17ca23a9f725d4bc8e62f5eb69f1e02abaa3960dfef6711dd059ef38e7d97abe2e4af69e68a630bf8728ab3afbfb0ad
+  metadata.gz: bfc6ff5b7a9e706be919eaf35fbdfe7b3c2575c68e03008f2381c723ab6896f9826047427e78e8915b90985c0ce26e04e83e639817dd5b7f40bbe1adc69e8aa8
+  data.tar.gz: ac2c8aa63ee627f73cd2d8a06071273bbbc8af64f9ae21862ff6f9bc235c7a0aa031c4fe601aea2b7e3ad4f93ef8ffd248fba35fbcf7cbabf422c37727995f72

data/.yardopts

@@ -1 +1,3 @@
---markup=markdown
+--markup=markdown
+-
+CHANGES.md

data/CHANGES.md

@@ -0,0 +1,14 @@
+0.1.0  / 2022-04
+------------------
+
+#### BREAKING changes
+* Changed option parsing.
+
+  {FFI::Libfuse::Main#fuse_options} now takes a FuseArgs parameter and fuse_opt_proc is not used
+
+#### New Features
+* Implemented helper filesystems in {FFI::Libfuse::Filesystem}
+
+#### Fixes
+* Test on OSX with macFuse
+* Lots

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Grant Gardner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -2,61 +2,160 @@
 
 Ruby FFI Binding for [libfuse](https://github.com/libfuse/libfuse)
 
-## Writing a FUSE Filesystem
+## Requirements
 
-Create a class that implements the abstract methods of {FFI::Libfuse::Main} and {FFI::Libfuse::FuseOperations}
+  * Ruby 2.7
+  * Linux: libfuse (Fuse2) or libfuse3 (Fuse3)
+  * MacOS: macFuse (https://osxfuse.github.io/)
 
-Call {FFI::Libfuse.fuse_main} to start the filesystem
+## Building a FUSE Filesystem
+
+Install the gem
+
+```bash
+gem install ffi-libfuse
+```
+
+Create a filesystem class
+
+* implement FUSE callbacks for filesystem operations satisfying {FFI::Libfuse::FuseOperations}
+* recommend including {FFI::Libfuse::Adapter::Ruby} to add some ruby sugar and safety to the native FUSE Callbacks
+* recommend including {FFI::Libfuse::Adapter::Fuse2Compat} for compatibility with Fuse2/macFuse
+* implement {FFI::Libfuse::Main} configuration methods, eg to parse custom options with {FFI::Libfuse::FuseArgs#parse!}
+  (as altered by any included adapters from {FFI::Libfuse::Adapter})
+* Provide an entrypoint to start the filesystem using {FFI::Libfuse::Main.fuse_main}
+
+{FFI::Libfuse::Filesystem} contains additional classes and modules to help build and compose filesystems 
+
+<!-- SAMPLE BEGIN: sample/hello_fs.rb -->
+*sample/hello_fs.rb*
 
 ```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require 'ffi/libfuse'
 
-class MyFS
-  # include helpers to abstract away from the native C callbacks to more idiomatic Ruby
+# Hello World!
+class HelloFS
   include FFI::Libfuse::Adapter::Ruby
-  
-  # ... FUSE callbacks .... quacks like a FFI:Libfuse::FuseOperations
-  def getattr(*args)
-    #...  
+  include FFI::Libfuse::Adapter::Fuse2Compat
+
+  # FUSE Configuration methods
+
+  def fuse_options(args)
+    args.parse!({ 'subject=' => :subject }) do |key:, value:, **|
+      raise FFI::Libfuse::Error, 'subject option must be at least 2 characters' unless value.size >= 2
+
+      @subject = value if key == :subject
+      :handled
+    end
   end
-  
-  def readdir(*args)
-    #...
+
+  def fuse_help
+    '-o subject=<subject>   a target to say hello to'
+  end
+
+  def fuse_configure
+    @subject ||= 'World!'
+    @content = "Hello #{@subject}\n"
+  end
+
+  # FUSE callbacks
+
+  def getattr(path, stat, *_args)
+    case path
+    when '/'
+      stat.directory(mode: 0o550)
+    when '/hello.txt'
+      stat.file(mode: 0o440, size: @content.size)
+    else
+      raise Errno::ENOENT
+    end
+  end
+
+  def readdir(_path, *_args)
+    yield 'hello.txt'
+  end
+
+  def read(_path, *_args)
+    @content
   end
-  
 end
 
-FFI::Libfuse::fuse_main(operations: MyFS.new) if __FILE__ == $0
+# Start the file system
+FFI::Libfuse.fuse_main(operations: HelloFS.new) if __FILE__ == $0
+
 ```
+<!-- SAMPLE END: sample/hello_fs.rb -->
 
-# Fuse2/Fuse3 compatibility
+Mount the filesystem
+
+```bash
+hello_fs.rb -h # show help
+hello_fs.rb /mnt/hello # run deamonized, mounted at /mnt/hello
+```
+
+Do file things
+
+```bash
+ls /mnt/hello
+cat /mnt/hello/hello.txt
+```
+
+## Fuse2/Fuse3 compatibility
 
 FFI::Libfuse will prefer Fuse3 over Fuse2 by default. See {FFI::Libfuse::LIBFUSE}
 
-For writing filesystems with backwards/forwards compatibility between fuse version see
-{FFI::Libfuse::Adapter::Fuse2Compat} and {FFI::Libfuse::Adapter::Fuse3Support}
+New filesystems should write for Fuse3 API and include {FFI::Libfuse::Adapter::Fuse2Compat} for backwards compatibility
+
+Alternatively filesystems written against Fuse2 API can include {FFI::Libfuse::Adapter::Fuse3Support}
 
 ## MACFuse
 
-[macFUSE](https://osxfuse.github.io/) (previously OSXFuse) supports a superset of the Fuse2 api so FFI::Libfuse is
- intended to work in that environment.
+[macFUSE](https://osxfuse.github.io/) (previously OSXFuse) supports a superset of the Fuse2 api
+
+**TODO** Implement macFuse extensions
+
+
+# Under the hood
+
+{FFI::Libfuse} provides raw access to the underlying libfuse but there some constraints imposed by Ruby.
+
+## Low-level functions re-implemented in Ruby
 
-# Multi-threading
+The C functions fuse_main(), fuse_daemonize() and fuse_loop<_mt>() are re-implemented to provide
 
-Most Ruby filesystems are unlikely to benefit from multi-threaded operation so
-{FFI::Libfuse.fuse_main} as shown above injects the '-s' (single-thread) option by default.
+* dynamic compatibility between Fuse2 and Fuse3
+* support for multi-threading under MRI
+* signal handling in ruby filesystem (eg HUP to reload)
 
-Pass the original options in directly if multi-threaded operation is desired for your filesystem
+The `-o native' option will use the native C functions but only exists to assist with testing that FFI::Libfuse has
+similar behaviour to C libfuse.
+
+See {FFI::Libfuse::Main} and {FFI::Libfuse::FuseCommon}
+
+## Multi-threading
+
+{FFI::Libfuse.fuse_main} forces the `-s` (single-thread) option to be set since most Ruby filesystems are
+unlikely to benefit from the overhead caused by multi-threaded operation obtaining/releasing the GVL around each
+callback.
+
+{FFI::Libfuse::Main.fuse_main} does not pass any options by default and should be used in situations where
+multi-threaded operations may be desirable.
 
 ```ruby
-FFI::Libfuse::fuse_main($0,*ARGV, operations: MyFS.new) if __FILE__ == $0
+FFI::Libfuse::Main.fuse_main(operations: MyFS.new) if __FILE__ == $0
 ```
 
-The {FFI::Libfuse::ThreadPool} can be configured with `-o max_threads=<n>,max_idle_threads=<n>` options
+The multi-thread loop uses {FFI::Libfuse::ThreadPool} to control thread usage and can be configured with options
+`-o max_threads=<n>,max_idle_threads=<n>`
 
-Callbacks that are about to block (and release the GVL for MRI) should call {FFI::Libfuse::ThreadPool.busy}.
+Callbacks that are about to block (and release the GVL for MRI) should call {FFI::Libfuse::ThreadPool.busy} which will
+spawn additional worker threads as required.
 
-A typical scenario would be a filesystem where some callbacks are blocking on network IO.
+Note that uncaught exceptions in callbacks will kill the worker thread and if all worker threads are dead the
+file system will stop and unmount. In particular if the first callback raises an exception
 
 ```ruby
 def read(*args)
@@ -70,29 +169,13 @@ end
 [this discussion](http://fuse.996288.n3.nabble.com/GetAttr-calls-being-serialised-td11741.html)
 on the serialisation of `#getattr` and `#readdir` calls.
 
-## Under the hood
+**TODO**  Build an example filesystem that makes use of multi-threading
 
-FFI::Libfuse tries to provide raw access to the underlying libfuse but there some constraints imposed by Ruby.
-
-The functions fuse_main(), fuse_daemonize() and fuse_loop<_mt>() are re-implemented in Ruby so we can provide
-
- * dynamic compatibility between Fuse2 and Fuse3
- * integrated support for multi-threading under MRI (see {FFI::Libfuse::ThreadPool})
- * signal handling in ruby filesystem (eg HUP to reload)
-
-Sending `-o native' will used the native C functions but this exists to assist with testing that FFI::Libfuse has
-similar behaviour to libfuse itself.
-
-See {FFI::Libfuse::Main} and {FFI::Libfuse::FuseCommon}
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/lwoggardner/ffi-libfuse. 
 
-### TODO
-  * Include a MetaFS, PathMapperFS etc (possibly a separate library)
-  * Build a filesystem that can make use of multi-threaded operations
-  * Test with macFUSE
 
 ## License
 

data/lib/ffi/accessors.rb

@@ -20,8 +20,8 @@ module FFI
       #
       # Define a struct attribute reader for members
       # @param [Array<Symbol>] attrs the attribute names
-      # @param [String] format
-      #   A format string containing a single %s to convert attr symbol to struct member
+      # @param [Proc|String] format
+      #   A Proc, or format string containing a single %s, to convert attr to struct member name
       # @param [Boolean] simple
       #   Controls how writer methods are defined using block
       # @param [Proc] block
@@ -33,7 +33,7 @@ module FFI
       # @return [void]
       def ffi_attr_reader(*attrs, format: '%s', simple: true, &block)
         attrs.each do |attr|
-          member = (format % attr).to_sym
+          member = (format.respond_to?(:call) ? format.call(attr) : format % attr).to_sym
           ffi_attr_readers[attr] = member
           if !block
             define_method(attr) { self[member] }
@@ -47,7 +47,7 @@ module FFI
 
       # Define a struct attribute writer
       # @param [Array<Symbol>] attrs the attribute names
-      # @param [String] format
+      # @param [String|Proc] format
       #   A format string containing a single %s to convert attr symbol to struct member
       # @param [Boolean] simple
       #   Controls how writer methods are defined using block
@@ -55,8 +55,8 @@ module FFI
       #   An optional block to set the input value into the struct field.
       #
       #   If simple is true then the struct field is set to the result of calling block with the input value,
-      #   otherwise the method is defined directly from the block. Use __method__[0..-2] to get the attribute name
-      #   and self.class.ffi_attr_writers[__method__[0..-2]] to get the struct field name
+      #   otherwise the method is defined directly from the block. Use __method__[0..-1] to get the attribute name
+      #   and self.class.ffi_attr_writers[__method__[0..-1]] to get the struct member name
       # @return [void]
       def ffi_attr_writer(*attrs, format: '%s', simple: true, &block)
         attrs.each do |attr|

data/lib/ffi/boolean_int.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FFI
+  # Converter generator for different sizes ints as boolean
+  class BooleanInt
+    include DataConverter
+    attr_reader :native_type
+
+    def initialize(int_type)
+      @native_type = FFI.find_type(int_type)
+    end
+
+    # Falsey = 0, Truthy = 1
+    def to_native(obj, _context)
+      obj ? 1 : 0
+    end
+
+    # Not Zero
+    def from_native(object_id, _context)
+      !object_id.zero?
+    end
+
+    %i[char short int long int8 int16 int32 int64].each do |t|
+      FFI.typedef(BooleanInt.new(t), "bool_#{t}".to_sym)
+    end
+  end
+end

data/lib/ffi/devt.rb

@@ -26,5 +26,28 @@ module FFI
     #  @param [Integer] dev
     #  @return [Integer] the minor component of dev
     attach_function :minor, "#{prefix}minor".to_sym, [:int], :int
+  rescue FFI::NotFoundError
+    case Platform::NAME
+    when 'x86_64-darwin'
+      # From https://github.com/golang/go/issues/8106 these functions are not defined on Darwin.
+      class << self
+        # define	major(x)	((int32_t)(((u_int32_t)(x) >> 24) & 0xff))
+        def major(dev)
+          (dev >> 24) & 0xff
+        end
+
+        # define	minor(x)	((int32_t)((x) & 0xffffff))
+        def minor(dev)
+          (dev & 0xffffff)
+        end
+
+        # define	makedev(x,y) ((dev_t)(((x) << 24) | (y)))
+        def makedev(major, minor)
+          (major << 24) | minor
+        end
+      end
+    else
+      raise
+    end
   end
 end

data/lib/ffi/encoding.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module FFI
+  # DataConverter for reading/writing encoded strings
+  class Encoding
+    include DataConverter
+
+    attr_reader :encoding
+
+    # Create a dataconverter for the specified encoding
+    # @example
+    #   module MyFFIModule
+    #     extend FFI::Library
+    #     typedef FFI::Encoding.for('utf8'), :utf8_string
+    #   end
+    def self.for(encoding)
+      new(encoding)
+    end
+
+    def from_native(value, _ctx)
+      value.force_encoding(encoding)
+    end
+
+    def to_native(value, _ctx)
+      value.encode(encoding)
+    end
+
+    def native_type(_type = nil)
+      FFI::Type::STRING
+    end
+
+    def initialize(encoding)
+      @encoding = encoding
+    end
+  end
+end

data/lib/ffi/gnu_extensions.rb

@@ -27,7 +27,7 @@ module FFI
   module GNUExtensions
     if FFI::Platform::IS_GNU
       extend FFI::Library
-      ffi_lib 'libdl'
+      ffi_lib(%w[libdl.so libdl.so.2].flat_map { |l| [l, "#{FFI::Platform::NAME}-gnu/#{l}"] })
 
       # @!method dlopen(library,type)
       #   @return [FFI::Pointer] library address, possibly NULL

data/lib/ffi/libfuse/ackbar.rb

@@ -29,15 +29,15 @@ module FFI
       end
 
       # @param [Hash<Symbol|String|Integer,String|Proc>] traps
-      #   Map of signal or signo to signal handler as per Signal.trap
+      #   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
+      #   Unless set, only installs traps currently set to 'DEFAULT'.
       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
+        @restore = @traps.to_h { |sig, handler| [sig, trap(sig, handler, force: force)] }
       end
 
       # Handle the next available signal on the pipe (without blocking)

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

@@ -5,15 +5,14 @@ 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
+      # Injects a wrapper via #{FuseCallbacks#fuse_wrappers} make the current {FuseContext} object available to
+      #  callbacks (except :destroy) via thread local variable :fuse_context
       module Context
         # @!visibility private
         def fuse_wrappers(*wrappers)
           wrappers.unshift(
             {
-              wrapper: proc { |_fm, *args, **_, &b| self.class.context_callback(*args, &b) },
+              wrapper: proc { |_fm, *args, **_, &b| Context.thread_local_context(*args, &b) },
               excludes: %i[destroy]
             }
           )
@@ -24,12 +23,15 @@ module FFI
 
         module_function
 
-        # @yieldparam [FuseContext] ctx
-        # @yieldparam [Array] *args
-        def context_callback(*args)
-          ctx = FuseContext.get
-          ctx = nil if ctx.null?
-          yield ctx, *args
+        # Capture {FuseContext} in thread local variable
+        def fuse_context
+          Thread.current[:fuse_context] ||= FuseContext.get
+        end
+
+        def thread_local_context(*args)
+          yield(*args)
+        ensure
+          Thread.current[:fuse_context] = nil
         end
       end
     end

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

@@ -5,77 +5,78 @@ module FFI
     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
+        module Prepend
           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
+          if FUSE_MAJOR_VERSION == 2
+            # @!visibility private
+            def getattr(path, stat, fuse_file_info = nil)
+              super(path, stat, fuse_file_info)
+            end
 
-          def init(fuse_conn_info, fuse_config = nil)
-            super(fuse_conn_info, fuse_config)
-          end
+            def truncate(path, size, fuse_file_info = nil)
+              super(path, size, fuse_file_info)
+            end
 
-          def chown(path, uid, gid, fuse_file_info = nil)
-            super(path, uid, gid, fuse_file_info)
-          end
+            def init(fuse_conn_info, fuse_config = nil)
+              super(fuse_conn_info, fuse_config)
+            end
 
-          def chmod(path, mode, fuse_file_info = nil)
-            super(path, mode, fuse_file_info)
-          end
+            def chown(path, uid, gid, fuse_file_info = nil)
+              super(path, uid, gid, fuse_file_info)
+            end
 
-          def utimens(path, atime, mtime, fuse_file_info = nil)
-            super(path, atime, mtime, fuse_file_info)
-          end
+            def chmod(path, mode, fuse_file_info = nil)
+              super(path, mode, 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 utimens(path, atime, mtime, fuse_file_info = nil)
+              super(path, atime, mtime, fuse_file_info)
+            end
 
-          def fgetattr(*args)
-            getattr(*args)
-          end
+            def readdir(path, buffer, filler, offset, fuse_file_info, fuse_readdir_flag = 0)
+              f3_fill = proc { |buf, name, stat, off = 0, _fuse_fill_dir_flag = 0| filler.call(buf, name, stat, off) }
+              super(path, buffer, f3_fill, offset, fuse_file_info, fuse_readdir_flag)
+            end
 
-          def ftruncate(*args)
-            truncate(*args)
-          end
+            def fgetattr(path, stat, ffi)
+              stat.clear # For some reason (at least on OSX) the stat is not clear when this is called.
+              getattr(path, stat, ffi)
+              0
+            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 ftruncate(*args)
+              truncate(*args)
+            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?
+            def fuse_respond_to?(fuse_method)
+              fuse_method = fuse_method[1..].to_sym if %i[fgetattr ftruncate].include?(fuse_method)
+              super(fuse_method)
             end
 
-            res
-          end
-        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
 
-        # @!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)
+              res
+            end
+
+          else
+            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
         end
 
         # @!visibility private
         def self.included(mod)
-          prepend_module = Libfuse.FUSE_MAJOR_VERSION == 2 ? Fuse2Prepend : Fuse3Prepend
-          mod.prepend(prepend_module)
+          mod.prepend(Prepend)
         end
 
         # @!method init_fuse_config(fuse_config,compat)

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

@@ -12,7 +12,6 @@ module FFI
       #
       module Fuse3Support
         # The actual module methods that are prepended
-        # @!visibility private
         module Prepend
           include Adapter