cruise 0.0.0 → 0.2.0

data/Cargo.toml

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Marco Roth
+
+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

@@ -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

@@ -1,12 +1,89 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
+require "rake/testtask"
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.libs << "ext"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
 
-require "rubocop/rake_task"
+begin
+  require "rake/extensiontask"
 
-RuboCop::RakeTask.new
+  PLATFORMS = [
+    "aarch64-linux-gnu",
+    "aarch64-linux-musl",
+    "arm-linux-gnu",
+    "arm64-darwin",
+    "x86_64-darwin",
+    "x86_64-linux-gnu",
+    "x86_64-linux-musl"
+  ].freeze
 
-task default: %i[test rubocop]
+  RB_SYS_PLATFORM_MAP = {
+    "aarch64-linux-gnu" => "aarch64-linux",
+    "aarch64-linux-musl" => "aarch64-linux-musl",
+    "arm-linux-gnu" => "arm-linux",
+    "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",
+  }.freeze
+
+  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
+
+  namespace "gem" do
+    task "prepare" do
+      require "rake_compiler_dock"
+
+      sh "bundle config set cache_all true"
+
+      gemspec_path = File.expand_path("./cruise.gemspec", __dir__)
+      spec = eval(File.read(gemspec_path), binding, gemspec_path)
+
+      RakeCompilerDock.set_ruby_cc_version(spec.required_ruby_version.as_list)
+    rescue LoadError
+      abort "rake_compiler_dock is required for this task"
+    end
+
+    PLATFORMS.each do |platform|
+      desc "Build all native binary gems in parallel"
+      multitask "native" => platform
+
+      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(
+          "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}"
+        )
+      end
+    end
+  end
+rescue LoadError => e
+  warn "WARNING: Failed to load extension tasks: #{e.message}"
+
+  desc "Compile task not available (rake-compiler not installed)"
+  task :compile do
+    abort "rake-compiler is required: #{e.message}\n\nRun: bundle install"
+  end
+end
+
+task test: :compile
+task default: [:compile, :test]

data/cruise.gemspec

@@ -8,21 +8,33 @@ 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"
 
-  spec.required_ruby_version = ">= 3.1.0"
+  spec.required_ruby_version = ">= 3.2.0"
   spec.require_paths = ["lib"]
 
   spec.files = Dir[
     "cruise.gemspec",
     "LICENSE.txt",
+    "README.md",
+    "Cargo.toml",
+    "Cargo.lock",
     "Rakefile",
-    "lib/**/*.rb"
+    "lib/**/*.rb",
+    "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"]
+
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["rubygems_mfa_required"] = "true"
   spec.metadata["homepage_uri"] = spec.homepage

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);
+}