cruise 0.1.0-x86_64-linux-gnu → 0.2.0-x86_64-linux-gnu

data/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["ext/cruise"]
+resolver = "2"

data/README.md

@@ -0,0 +1,223 @@
+<div align="center">
+  <h1>Cruise</h1>
+  <h4>A fast, OS-native file watcher for Ruby.</h4>
+
+  <p>
+    <a href="https://rubygems.org/gems/cruise"><img alt="Gem Version" src="https://img.shields.io/gem/v/cruise"></a>
+    <a href="https://github.com/marcoroth/cruise/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/marcoroth/cruise"></a>
+  </p>
+
+  <p>A file system watcher built on native OS events, not polling.<br/>Uses FSEvents on macOS and inotify on Linux.</p>
+</div>
+
+Cruise was originally built to power file watching in the [Herb](https://herb-tools.dev) dev server, none of the existing Ruby watchers were quite reliable enough for the realtime hot reloading that a local development server and workflow needs. It also works standalone for any project that needs to react to file changes.
+
+## Installation
+
+**Add to your Gemfile:**
+
+```ruby
+gem "cruise"
+```
+
+**Or install directly:**
+
+```bash
+gem install cruise
+```
+
+Precompiled native gems are available for macOS and Linux. If a precompiled gem isn't available for your platform, it will compile from source (requires Rust).
+
+## Usage
+
+### Basic Example
+
+Watch a directory for changes:
+
+```ruby
+require "cruise"
+
+Cruise.watch("app/views") do |event|
+  puts "#{event.kind}: #{event.path}"
+end
+```
+
+The callback receives a `Cruise::Event` with two attributes:
+
+| Attribute    | Description                                                                            |
+|--------------|----------------------------------------------------------------------------------------|
+| `event.path` | Absolute path to the changed file                                                      |
+| `event.kind` | One of: `"created"`, `"modified"`, `"renamed"`, `"removed"`, `"accessed"`, `"changed"` |
+
+### Multiple Directories
+
+Watch several paths at once:
+
+```ruby
+Cruise.watch("app/views", "app/components", "lib/templates") do |event|
+  puts event.inspect
+  # => #<Cruise::Event kind="modified" path="/app/views/users/show.html.erb">
+end
+```
+
+### Ruby Threads
+
+Cruise releases the GVL while waiting for filesystem events, so Ruby threads run freely:
+
+```ruby
+Thread.new { do_background_work }
+
+Cruise.watch("src") do |event|
+  puts event
+end
+```
+
+### Glob Filtering
+
+Only receive events for files matching a pattern:
+
+```ruby
+Cruise.watch("app/views", glob: "**/*.html.erb") do |event|
+  puts event
+end
+```
+
+Multiple patterns:
+
+```ruby
+Cruise.watch("app", glob: ["**/*.html.erb", "**/*.html"]) do |event|
+  puts event
+end
+```
+
+### Debounce
+
+Configure the debounce interval (default: 100ms):
+
+```ruby
+Cruise.watch("src", debounce: 0.5) do |event|
+  puts event
+end
+```
+
+### Proc Callback
+
+You can also pass a `Proc` via the `callback:` keyword:
+
+```ruby
+handler = proc { |event| puts event }
+
+Cruise.watch("app/views", callback: handler)
+```
+
+### Stopping
+
+The watcher runs in a blocking loop. Use `Interrupt` to stop it cleanly:
+
+```ruby
+begin
+  Cruise.watch("app") do |event|
+    # process event
+  end
+rescue Interrupt
+  puts "Stopped."
+end
+```
+
+### Async / Fibers
+
+`Cruise.watch` cooperates with Ruby's fiber scheduler, the API is identical whether you're on threads or fibers, with no separate "async mode." It waits on an internal pipe via `IO#wait_readable`, which yields to other fibers when a scheduler is active (for example inside [`Async`](https://github.com/socketry/async)) and otherwise blocks the thread with the GVL released.
+
+```ruby
+require "async"
+require "cruise"
+
+Async do |task|
+  task.async do
+    Cruise.watch("app/views", glob: "**/*.html.erb") do |event|
+      reload(event.path)
+    end
+  end
+
+  task.async do
+    start_dev_server
+  end
+end
+```
+
+Cruise doesn't depend on `async`, it only relies on the standard `IO#wait_readable` hook, so any `Fiber::Scheduler` works.
+
+#### Lower-level watcher
+
+For custom event loops or manually-driven fibers, `Cruise::Watcher` exposes a readable `IO` and a non-blocking `#poll`:
+
+```ruby
+watcher = Cruise::Watcher.new("app/views", glob: "**/*.erb", debounce: 0.1)
+
+begin
+  loop do
+    watcher.io.wait_readable
+    watcher.io.read_nonblock(4096, exception: false)  
+
+    while (event = watcher.poll)
+      handle(event)
+    end
+  end
+ensure
+  watcher.close
+end
+```
+
+`Cruise::Watcher.new` takes the same paths keyword arguments as `Cruise.watch`, it's the watcher `Cruise.watch` runs internally.
+
+## How It Works
+
+Cruise is a Ruby C extension that links a Rust static library (`libcruise.a`) built around the [notify](https://github.com/notify-rs/notify) crate. The Rust core exposes a small C ABI (generated with [cbindgen](https://github.com/mozilla/cbindgen)) and knows nothing about Ruby. A thin hand-written C wrapper bridges that ABI to Ruby objects via the Ruby C API.
+
+1. `Cruise.watch` sets up a [notify](https://github.com/notify-rs/notify) watcher with event debouncing (100ms)
+2. A background thread monitors filesystem events using the OS-native API
+3. The main loop calls `rb_thread_call_without_gvl` to wait without blocking Ruby
+4. When an event arrives, the GVL is re-acquired and your callback is invoked
+
+### Platform Backends
+
+| Platform | Backend  | API                      |
+|----------|----------|--------------------------|
+| macOS    | FSEvents | `CoreServices` framework |
+| Linux    | inotify  | `inotify_init1` syscall  |
+
+All backends watch recursively by default.
+
+## Prior Art
+
+Cruise builds on ideas from the Ruby ecosystem's existing file watchers:
+
+- **[`listen`](https://github.com/guard/listen)** the long-standing workhorse behind Guard, Rails, and much of the ecosystem. Wraps [rb-fsevent](https://github.com/guard/rb-fsevent) (macOS) and [rb-inotify](https://github.com/guard/rb-inotify) (Linux), with a polling fallback for other platforms and network shares.
+- **[`guard`](https://github.com/guard/guard)** a command-line tool, built on listen, that runs tasks (tests, reloads, builds) in response to file changes.
+- **[`io-watch`](https://github.com/socketry/io-watch)** a newer, deliberately minimal library from the [socketry](https://github.com/socketry) project, offering one simple, unified directory-watching interface across platforms without per-platform multiplexing in application code.
+
+Cruise shares `io-watch`'s preference for a single, native-events-only interface over platform multiplexing. On top of that it focuses on what a hot-reload loop needs: built-in debouncing, glob and event-kind filtering, and precompiled native gems so there's nothing to build at install time on supported platforms. It deliberately has no polling adapter, so filesystems where native events aren't delivered fall outside its scope, reach for [listen](https://github.com/guard/listen) there.
+
+## Development
+
+**Requirements:** Rust toolchain, Ruby 3.2+
+
+```bash
+git clone https://github.com/marcoroth/cruise
+cd cruise
+bundle install
+bundle exec rake compile
+bundle exec rake test
+```
+
+### Cross-compilation
+
+Cruise uses [rake-compiler](https://github.com/rake-compiler/rake-compiler) and [rake-compiler-dock](https://github.com/rake-compiler/rake-compiler-dock) for building native gems:
+
+```bash
+bundle exec rake gem:native
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -6,13 +6,12 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
+  t.libs << "ext"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
 begin
   require "rake/extensiontask"
-  require "rb_sys"
-  require "rb_sys/extensiontask"
 
   PLATFORMS = [
     "aarch64-linux-gnu",
@@ -31,11 +30,15 @@ begin
     "arm64-darwin" => "arm64-darwin",
     "x86_64-darwin" => "x86_64-darwin",
     "x86_64-linux-gnu" => "x86_64-linux",
-    "x86_64-linux-musl" => "x86_64-linux-musl"
+    "x86_64-linux-musl" => "x86_64-linux-musl",
   }.freeze
 
-  RbSys::ExtensionTask.new("cruise", Gem::Specification.load("cruise.gemspec")) do |ext|
+  Rake::ExtensionTask.new do |ext|
+    ext.name = "cruise"
+    ext.source_pattern = "*.{c,h}"
+    ext.ext_dir = "ext/cruise"
     ext.lib_dir = "lib/cruise"
+    ext.gem_spec = Gem::Specification.load("cruise.gemspec")
     ext.cross_compile = true
     ext.cross_platform = PLATFORMS
   end
@@ -60,10 +63,13 @@ begin
 
       desc "Build the native gem for #{platform}"
       task platform => "prepare" do
+        require "rb_sys"
+
         rb_sys_platform = RB_SYS_PLATFORM_MAP.fetch(platform)
 
         RakeCompilerDock.sh(
-          "bundle install && bundle exec rake native:#{platform} gem RUBY_CC_VERSION='#{ENV.fetch("RUBY_CC_VERSION", nil)}'",
+          "export RCD_PLATFORM=#{platform} && " \
+          "bundle --local && rake native:#{platform} gem RUBY_CC_VERSION='#{ENV.fetch("RUBY_CC_VERSION", nil)}'",
           platform: platform,
           image: "rbsys/#{rb_sys_platform}:#{RbSys::VERSION}"
         )
@@ -79,4 +85,5 @@ rescue LoadError => e
   end
 end
 
+task test: :compile
 task default: [:compile, :test]

data/cruise.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Marco Roth"]
   spec.email = ["marco.roth@intergga.ch"]
 
-  spec.summary = "A fast, native file watcher for Ruby"
-  spec.description = "Cruise is a Rust-powered file system watcher with native OS integration. Uses FSEvents on macOS and inotify on Linux."
+  spec.summary = "A fast, OS-native file watcher for Ruby"
+  spec.description = "Cruise is a file system watcher built on native OS events. Uses FSEvents on macOS and inotify on Linux."
   spec.homepage = "https://github.com/marcoroth/cruise"
   spec.license = "MIT"
 
@@ -19,10 +19,18 @@ Gem::Specification.new do |spec|
   spec.files = Dir[
     "cruise.gemspec",
     "LICENSE.txt",
+    "README.md",
     "Cargo.toml",
+    "Cargo.lock",
     "Rakefile",
     "lib/**/*.rb",
-    "ext/**/*.{rs,toml,rb,lock}"
+    "ext/cruise/build.rs",
+    "ext/cruise/Cargo.toml",
+    "ext/cruise/cbindgen.toml",
+    "ext/cruise/cruise.c",
+    "ext/cruise/extconf.rb",
+    "ext/cruise/include/**/*.h",
+    "ext/cruise/src/**/*.rs"
   ]
 
   spec.extensions = ["ext/cruise/extconf.rb"]
@@ -33,6 +41,4 @@ Gem::Specification.new do |spec|
   spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
-
-  spec.add_dependency "rb_sys"
 end

data/ext/cruise/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "cruise"
+version = "0.2.0"
+edition = "2021"
+authors = ["Marco Roth <marco.roth@intergga.ch>"]
+description = "A fast, OS-native file watcher for Ruby"
+license = "MIT"
+publish = false
+
+[lib]
+name = "cruise"
+path = "src/lib.rs"
+crate-type = ["staticlib"]
+
+[dependencies]
+notify = { version = "7", features = ["macos_fsevent"] }
+notify-debouncer-full = "0.4"
+globset = "0.4"
+libc = "0.2"
+
+[build-dependencies]
+cbindgen = "0.28"

data/ext/cruise/build.rs

@@ -0,0 +1,15 @@
+use std::env;
+use std::fs;
+use std::path::PathBuf;
+
+fn main() {
+  let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
+  let include_dir = PathBuf::from(&crate_dir).join("include");
+  let header_path = include_dir.join("cruise.h");
+
+  let _ = fs::create_dir_all(&include_dir);
+
+  if let Ok(bindings) = cbindgen::generate(&crate_dir) {
+    bindings.write_to_file(&header_path);
+  }
+}

data/ext/cruise/cbindgen.toml

@@ -0,0 +1,23 @@
+language = "C"
+header = """/* Generated by cbindgen, do not edit manually */
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>"""
+include_guard = "CRUISE_H"
+no_includes = true
+
+[export]
+include = [
+  "CruiseEvent",
+]
+
+[enum]
+rename_variants = "ScreamingSnakeCase"
+prefix_with_name = true
+
+[fn]
+sort_by = "None"
+
+[parse]
+parse_deps = false

data/ext/cruise/cruise.c

@@ -0,0 +1,158 @@
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include <string.h>
+#include "include/cruise.h"
+
+static VALUE rb_mCruise;
+static VALUE rb_cWatcher;
+static VALUE rb_cEvent;
+
+static VALUE make_utf8_string(const char *cstring) {
+  return rb_enc_str_new_cstr(cstring, rb_utf8_encoding());
+}
+
+static void fill_c_strings(VALUE array, const char **buffer) {
+  long length = RARRAY_LEN(array);
+
+  for (long index = 0; index < length; index++) {
+    VALUE string = rb_ary_entry(array, index);
+
+    buffer[index] = StringValueCStr(string);
+  }
+}
+
+static void watcher_free(void *pointer) {
+  if (pointer) {
+    cruise_watcher_free((struct Watcher *) pointer);
+  }
+}
+
+static size_t watcher_size(const void *pointer) {
+  (void) pointer;
+
+  return sizeof(void *);
+}
+
+static const rb_data_type_t watcher_type = {
+  .wrap_struct_name = "Cruise::Watcher",
+  .function = {
+    .dfree = watcher_free,
+    .dsize = watcher_size,
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE watcher_alloc(VALUE klass) {
+  return TypedData_Wrap_Struct(klass, &watcher_type, NULL);
+}
+
+static struct Watcher *get_watcher(VALUE self) {
+  struct Watcher *watcher;
+
+  TypedData_Get_Struct(self, struct Watcher, &watcher_type, watcher);
+
+  return watcher;
+}
+
+static VALUE watcher_initialize_native(VALUE self, VALUE paths, VALUE debounce, VALUE globs, VALUE only_kinds) {
+  long path_count = RARRAY_LEN(paths);
+  long glob_count = RARRAY_LEN(globs);
+  long only_count = RARRAY_LEN(only_kinds);
+
+  const char **path_pointers = path_count > 0 ? ALLOCA_N(const char *, path_count) : NULL;
+  const char **glob_pointers = glob_count > 0 ? ALLOCA_N(const char *, glob_count) : NULL;
+  const char **only_pointers = only_count > 0 ? ALLOCA_N(const char *, only_count) : NULL;
+
+  if (path_pointers) fill_c_strings(paths, path_pointers);
+  if (glob_pointers) fill_c_strings(globs, glob_pointers);
+  if (only_pointers) fill_c_strings(only_kinds, only_pointers);
+
+  int read_fd = -1;
+  char *error = NULL;
+
+  struct Watcher *watcher = cruise_watcher_new(
+    path_pointers, (size_t) path_count,
+    NUM2DBL(debounce),
+    glob_pointers, (size_t) glob_count,
+    only_pointers, (size_t) only_count,
+    &read_fd,
+    &error
+  );
+
+  if (!watcher) {
+    VALUE message = error ? make_utf8_string(error) : rb_str_new_cstr("Failed to create watcher");
+
+    if (error) cruise_string_free(error);
+
+    const char *message_cstr = StringValueCStr(message);
+    VALUE error_class = rb_eRuntimeError;
+
+    if (strstr(message_cstr, "does not exist") || strstr(message_cstr, "Invalid glob pattern")) {
+      error_class = rb_eArgError;
+    }
+
+    rb_raise(error_class, "%s", message_cstr);
+  }
+
+  RTYPEDDATA_DATA(self) = watcher;
+
+  VALUE io = rb_funcall(rb_cIO, rb_intern("for_fd"), 2, INT2NUM(read_fd), rb_str_new_cstr("r"));
+  rb_iv_set(self, "@io", io);
+
+  return self;
+}
+
+// watcher.io
+static VALUE watcher_io(VALUE self) {
+  return rb_iv_get(self, "@io");
+}
+
+// watcher.poll
+static VALUE watcher_poll(VALUE self) {
+  struct Watcher *watcher = get_watcher(self);
+
+  if (!watcher) return Qnil;
+
+  CruiseEvent event = { NULL, NULL };
+
+  if (!cruise_watcher_poll(watcher, &event)) return Qnil;
+
+  VALUE path = make_utf8_string(event.path);
+  VALUE kind = make_utf8_string(event.kind);
+
+  cruise_string_free(event.path);
+  cruise_string_free(event.kind);
+
+  return rb_funcall(rb_cEvent, rb_intern("new"), 2, path, kind);
+}
+
+// watcher.close
+static VALUE watcher_close(VALUE self) {
+  struct Watcher *watcher = get_watcher(self);
+
+  if (watcher) {
+    cruise_watcher_free(watcher);
+    RTYPEDDATA_DATA(self) = NULL;
+  }
+
+  VALUE io = rb_iv_get(self, "@io");
+
+  if (!NIL_P(io) && !RTEST(rb_funcall(io, rb_intern("closed?"), 0))) {
+    rb_funcall(io, rb_intern("close"), 0);
+  }
+
+  return Qnil;
+}
+
+void Init_cruise(void) {
+  rb_mCruise = rb_define_module("Cruise");
+  rb_cEvent = rb_const_get(rb_mCruise, rb_intern("Event"));
+
+  rb_cWatcher = rb_define_class_under(rb_mCruise, "Watcher", rb_cObject);
+
+  rb_define_alloc_func(rb_cWatcher, watcher_alloc);
+  rb_define_private_method(rb_cWatcher, "initialize_native", watcher_initialize_native, 4);
+  rb_define_method(rb_cWatcher, "io", watcher_io, 0);
+  rb_define_method(rb_cWatcher, "poll", watcher_poll, 0);
+  rb_define_method(rb_cWatcher, "close", watcher_close, 0);
+}

data/ext/cruise/extconf.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "fileutils"
+
+crate_dir = __dir__
+root_dir = File.expand_path("../..", __dir__)
+
+unless system("cargo --version > /dev/null 2>&1")
+  abort <<~MESSAGE
+
+    ERROR: Rust toolchain not found.
+
+    cruise requires the Rust toolchain to compile from source.
+
+    Install Rust: https://rustup.rs
+
+  MESSAGE
+end
+
+RUST_TARGETS = {
+  "aarch64-linux-gnu" => "aarch64-unknown-linux-gnu",
+  "aarch64-linux-musl" => "aarch64-unknown-linux-musl",
+  "arm-linux-gnu" => "armv7-unknown-linux-gnueabihf",
+  "arm-linux-musl" => "armv7-unknown-linux-musleabihf",
+  "arm64-darwin" => "aarch64-apple-darwin",
+  "x86_64-darwin" => "x86_64-apple-darwin",
+  "x86_64-linux-gnu" => "x86_64-unknown-linux-gnu",
+  "x86_64-linux-musl" => "x86_64-unknown-linux-musl",
+  "x86-linux-gnu" => "i686-unknown-linux-gnu",
+  "x86-linux-musl" => "i686-unknown-linux-musl",
+}.freeze
+
+cross_compiling = ENV.key?("RUBY_CC_VERSION")
+target_platform = ENV.fetch("CARGO_BUILD_TARGET", nil)
+
+if cross_compiling && target_platform.nil?
+  rcd_platform = ENV.fetch("RCD_PLATFORM", "")
+  target_platform = RUST_TARGETS[rcd_platform]
+
+  if target_platform.nil?
+    ruby_platform = RbConfig::CONFIG["arch"]
+    target_platform = RUST_TARGETS.values.find { |t| ruby_platform.include?(t.split("-").first) }
+  end
+end
+
+workspace_target_dir = File.join(root_dir, "target")
+crate_target_dir = File.join(crate_dir, "target")
+
+if target_platform
+  puts "cruise: Cross-compiling Rust for target: #{target_platform}"
+  system("rustup target add #{target_platform}") || warn("cruise: Failed to add Rust target #{target_platform}")
+
+  cargo_args = "--release --target #{target_platform}"
+else
+  puts "cruise: Compiling Rust library for native platform..."
+
+  cargo_args = "--release"
+end
+
+unless system("cd #{root_dir} && cargo build #{cargo_args}")
+  abort "ERROR: Failed to compile cruise from Rust source."
+end
+
+lib_dir = if target_platform
+            [workspace_target_dir, crate_target_dir]
+              .map { |dir| File.join(dir, target_platform, "release") }
+              .find { |dir| Dir.exist?(dir) } || File.join(crate_target_dir, target_platform, "release")
+          else
+            [workspace_target_dir, crate_target_dir]
+              .map { |dir| File.join(dir, "release") }
+              .find { |dir| Dir.exist?(dir) } || File.join(crate_target_dir, "release")
+          end
+
+host_os = target_platform || RbConfig::CONFIG["host_os"]
+
+lib_name = case host_os
+           when /darwin/ then "libcruise.dylib"
+           when /mingw|mswin|windows/ then "cruise.dll"
+           else "libcruise.so"
+           end
+
+static_lib = File.join(lib_dir, "libcruise.a")
+
+if File.exist?(static_lib)
+  puts "cruise: Static library found at #{static_lib}"
+  $LDFLAGS << " #{static_lib}"
+else
+  lib_path = File.join(lib_dir, lib_name)
+
+  unless File.exist?(lib_path)
+    abort "ERROR: cruise library not found at #{static_lib} or #{lib_path}"
+  end
+
+  puts "cruise: Shared library found at #{lib_path} (dynamic)"
+
+  $LDFLAGS << " -L#{lib_dir} -lcruise"
+
+  if host_os.match?(/darwin|linux/)
+    $LDFLAGS << " -Wl,-rpath,#{lib_dir}"
+  end
+end
+
+case host_os
+when /darwin/
+  $LDFLAGS << " -framework CoreServices -framework CoreFoundation -framework Security"
+when /linux/
+  $LDFLAGS << " -lpthread -ldl -lm"
+end
+
+$CFLAGS << " -I#{File.join(__dir__, "include")}"
+
+create_makefile("cruise/cruise")