ffi-libfuse 0.0.1.rctest12 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cc15469bfd68dbe59e7b5dfab82fc1b34fe51e7e3b61e44c686d8a8025ec5ff
-  data.tar.gz: 691758dbb28272d60cfc1f5f2f37e8cef56de15412706b303f181c5b31cdf03f
+  metadata.gz: 688ea85b8e5ee83a4baae3055c14026e65e929c2e22a8d9a2d0e983584e8bd7b
+  data.tar.gz: 552a053bea357d44ccf6fa2fcc12d311116d66320e113d7de7acb929a8ac539e
 SHA512:
-  metadata.gz: 6dfefe8f3a512dcaa6f2ca34c3f45cba0fb61e17af4dc0114b9fec6a1adc7a63b0f156415b69e256b9bae97d5a9574626001e285f85ddaae985df84d840b2ca3
-  data.tar.gz: cb4d1f15b5220c9ec4c16a2c0874c082b17ca23a9f725d4bc8e62f5eb69f1e02abaa3960dfef6711dd059ef38e7d97abe2e4af69e68a630bf8728ab3afbfb0ad
+  metadata.gz: ca1a1f2b2b9573c523583f0ee9d8fa05fecbbaf4ba36fbe73b4db5090626b8fc984091880677b4654caacda25d6e073b0a679b57539f6faecfd4c62f5bc45257
+  data.tar.gz: f8cb9a7d82ac0be86249066b9b69d2cfe03be3e6eb028881b16e715766b2a0f9dbba46ba2478310be75677e2b8c188f0b26235bbfa491dc42d9dff0ca904840e

data/.yardopts

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

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## [0.3.3](https://github.com/lwoggardner/ffi-libfuse/compare/v0.0.1...v0.3.3) (2023-01-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* Support downstream RFuse/RFuseFS
+
+### Features
+
+* FFI::Libfuse::Filesystem - base filesystems ([5b19005](https://github.com/lwoggardner/ffi-libfuse/commit/5b19005c4b1ff2237b85c4854f481ea6e3625c62))
+
+
+### Code Refactoring
+
+* Support downstream RFuse/RFuseFS ([e6b3fb5](https://github.com/lwoggardner/ffi-libfuse/commit/e6b3fb552b8881dbf28f014617b7412f2542aaa3))
+
+
+### Miscellaneous Chores
+
+* **github:** release 0.3.3 ([b54a56f](https://github.com/lwoggardner/ffi-libfuse/commit/b54a56f3f93f15c7684aa2cb2c2dd38c9d033e7f))
+
+## [0.3.2](https://github.com/lwoggardner/ffi-libfuse/compare/v0.3.0...v0.3.2) (2023-01-07)
+
+
+### Miscellaneous Chores
+
+* fix release-please action ([fd55030](https://github.com/lwoggardner/ffi-libfuse/commit/fd550301248ebd9616da457ef8c2d88a7e55f819))
+
+## [0.3.0](https://github.com/lwoggardner/ffi-libfuse/compare/v0.2.1...v0.3.0) (2023-01-07)
+
+
+### Miscellaneous Chores
+
+* fix release-please action ([57d43e9](https://github.com/lwoggardner/ffi-libfuse/commit/57d43e9cac552b1b36469092a6278058893cadc4))
+
+## [0.2.1](https://github.com/lwoggardner/ffi-libfuse/compare/v0.1.0...v0.2.1) (2023-01-07)
+
+### Miscellaneous Chores
+
+* release 0.2.1 ([bb0ef37](https://github.com/lwoggardner/ffi-libfuse/commit/bb0ef37c05a41c6b51a14e5cae292b2d7b75ef1c))
+
+## [0.1.0](https://github.com/lwoggardner/ffi-libfuse/compare/v0.0.1...v0.1.0) (2023-01-07)
+
+### ⚠ BREAKING CHANGES
+
+* Support downstream RFuse/RFuseFS
+* Changed option parsing.
+
+  {FFI::Libfuse::Main#fuse_options} takes a FuseArgs parameter and fuse_opt_proc is not used
+
+### Features
+
+* FFI::Libfuse::Filesystem - base filesystems ([5b19005](https://github.com/lwoggardner/ffi-libfuse/commit/5b19005c4b1ff2237b85c4854f481ea6e3625c62))
+
+### Code Refactoring
+
+* Support downstream RFuse/RFuseFS ([e6b3fb5](https://github.com/lwoggardner/ffi-libfuse/commit/e6b3fb552b8881dbf28f014617b7412f2542aaa3))
+* Test on OSX with macFuse

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/flock.rb

@@ -12,18 +12,20 @@ module FFI
       SeekWhenceShort = enum :short, seek_whence
       SeekWhence = enum :int, seek_whence
 
-      LockType = enum :short, %i[f_rdlck f_wrlck f_unlck]
-      LockCmd = enum :int, [:f_getlk, 5, :f_setlk, 6, :f_setlkw, 7]
+      LockType = enum :short, %i[rdlck wrlck unlck]
+      LockCmd = enum :int, [:getlk, 5, :setlk, 6, :setlkw, 7]
     end
 
     include(Accessors)
 
-    layout(type: Enums::LockType, whence: Enums::SeekWhenceShort, start: :off_t, len: :off_t, pid: :pid_t)
+    layout(l_type: Enums::LockType, l_whence: Enums::SeekWhenceShort, l_start: :off_t, l_len: :off_t, l_pid: :pid_t)
 
-    ffi_attr_reader :type, :whence, :start, :len, :pid
+    l_members = members.grep(/^l_/).map { |m| m[2..].to_sym }
+
+    ffi_attr_reader(*l_members, format: 'l_%s')
 
     # @!attribute [r] type
-    #   @return [Symbol] lock type, :f_rdlck, :f_wrlck, :f_unlck
+    #   @return [Symbol] lock type, :rdlck, :wrlck, :unlck
 
     # @!attribute [r] whence
     #   @return [Symbol] specifies what the offset is relative to, one of :seek_set, :seek_cur or :seek_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