cruise 0.0.0 → 0.2.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")

data/ext/cruise/src/ffi.rs

@@ -0,0 +1,124 @@
+//! C ABI for Cruise.
+//!
+//! # Safety
+//!
+//! Pointer arguments must be valid (or null where documented). String arrays
+//! are `(pointer, count)` pairs of NUL-terminated UTF-8 C strings. Any C string
+//! returned through an out-parameter is heap-allocated by Rust and must be
+//! released with [`cruise_string_free`]; the watcher handle with
+//! [`cruise_watcher_free`]. The read fd returned by [`cruise_watcher_new`] is
+//! transferred to the caller, who is responsible for closing it.
+
+#![allow(clippy::missing_safety_doc)]
+
+use std::ffi::{CStr, CString};
+use std::os::raw::{c_char, c_int};
+use std::ptr;
+
+use crate::Watcher;
+
+/// A single filesystem event handed to the C side. Both strings are owned by
+/// the caller once populated and must be freed with [`cruise_string_free`].
+#[repr(C)]
+pub struct CruiseEvent {
+  pub path: *mut c_char,
+  pub kind: *mut c_char,
+}
+
+unsafe fn c_string_array(pointer: *const *const c_char, count: usize) -> Vec<String> {
+  if pointer.is_null() || count == 0 {
+    return Vec::new();
+  }
+
+  std::slice::from_raw_parts(pointer, count)
+    .iter()
+    .filter_map(|&entry| {
+      if entry.is_null() {
+        None
+      } else {
+        CStr::from_ptr(entry).to_str().ok().map(|value| value.to_string())
+      }
+    })
+    .collect()
+}
+
+/// Create a watcher over `paths`, filtered by `globs` and `only_kinds`.
+///
+/// On success returns a heap-allocated handle and writes the read end of the
+/// event pipe to `out_read_fd` (ownership transfers to the caller). On error
+/// returns null and, when `out_error` is non-null, writes a message to be freed
+/// with [`cruise_string_free`].
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_new(
+  paths: *const *const c_char,
+  path_count: usize,
+  debounce: f64,
+  globs: *const *const c_char,
+  glob_count: usize,
+  only_kinds: *const *const c_char,
+  only_count: usize,
+  out_read_fd: *mut c_int,
+  out_error: *mut *mut c_char,
+) -> *mut Watcher {
+  let paths = c_string_array(paths, path_count);
+  let globs = c_string_array(globs, glob_count);
+  let only = c_string_array(only_kinds, only_count);
+
+  match Watcher::new(&paths, debounce, &globs, only) {
+    Ok((watcher, read_fd)) => {
+      if !out_read_fd.is_null() {
+        *out_read_fd = read_fd;
+      }
+
+      Box::into_raw(Box::new(watcher))
+    }
+    Err(message) => {
+      if !out_error.is_null() {
+        *out_error = CString::new(message).unwrap_or_default().into_raw();
+      }
+
+      ptr::null_mut()
+    }
+  }
+}
+
+/// Non-blocking: pop the next queued event into `out_event` and return true, or
+/// return false if the queue is empty. Never touches Ruby and never blocks — the
+/// C wrapper waits on the pipe fd instead.
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_poll(watcher: *mut Watcher, out_event: *mut CruiseEvent) -> bool {
+  if watcher.is_null() {
+    return false;
+  }
+
+  let watcher = &*watcher;
+
+  match watcher.poll() {
+    Some((path, kind)) => {
+      if !out_event.is_null() {
+        (*out_event).path = CString::new(path).unwrap_or_default().into_raw();
+        (*out_event).kind = CString::new(kind).unwrap_or_default().into_raw();
+      }
+
+      true
+    }
+    None => false,
+  }
+}
+
+/// Free a watcher handle. Stops watching, joins the background thread, and
+/// closes the write end of the pipe (the reader then observes EOF).
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_free(watcher: *mut Watcher) {
+  if !watcher.is_null() {
+    drop(Box::from_raw(watcher));
+  }
+}
+
+/// Free a string previously returned by this library.
+#[no_mangle]
+pub unsafe extern "C" fn cruise_string_free(s: *mut c_char) {
+  if !s.is_null() {
+    drop(CString::from_raw(s));
+  }
+}

data/ext/cruise/src/lib.rs

@@ -0,0 +1,11 @@
+//! Cruise - a fast, OS-native file watcher.
+//!
+//! This crate contains the platform-agnostic watching logic ([`watcher`]) and a
+//! C ABI ([`ffi`]) that a thin Ruby C extension links against. It deliberately
+//! knows nothing about Ruby: it hands filtered `(path, kind)` pairs across the
+//! FFI boundary and lets the C wrapper turn them into Ruby objects.
+
+mod ffi;
+mod watcher;
+
+pub use watcher::Watcher;

data/ext/cruise/src/watcher.rs

@@ -0,0 +1,196 @@
+//! The platform-agnostic file watcher.
+//!
+//! Knows nothing about Ruby or the C ABI. It watches paths, applies the
+//! configured kind/glob filters on the debouncer's background thread, and
+//! pushes matching `(path, kind)` pairs onto a shared queue. A self-pipe is
+//! written to on every batch so a consumer can wait on a file descriptor
+//! (`IO#wait_readable`) instead of blocking a thread — which is what makes the
+//! watcher cooperate with Ruby's fiber scheduler.
+
+use std::any::Any;
+use std::collections::VecDeque;
+use std::os::fd::RawFd;
+use std::os::raw::{c_int, c_void};
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use globset::{Glob, GlobSet, GlobSetBuilder};
+use notify::event::{CreateKind, ModifyKind, RemoveKind};
+use notify::{EventKind, RecursiveMode};
+use notify_debouncer_full::{new_debouncer, DebounceEventResult};
+
+struct Shared {
+  pending: Mutex<VecDeque<(String, String)>>,
+  glob_set: Option<GlobSet>,
+  only_kinds: Vec<String>,
+  write_fd: RawFd,
+}
+
+impl Shared {
+  fn enqueue(&self, event: notify::Event) -> bool {
+    let kind = event_kind_to_string(&event.kind);
+
+    if !self.only_kinds.is_empty() && !self.only_kinds.iter().any(|allowed| allowed == kind) {
+      return false;
+    }
+
+    let mut queue = self.pending.lock().unwrap();
+    let mut added = false;
+
+    for path in event.paths {
+      if let Some(ref globs) = self.glob_set {
+        if !globs.is_match(&path) {
+          continue;
+        }
+      }
+
+      queue.push_back((path.to_string_lossy().into_owned(), kind.to_string()));
+      added = true;
+    }
+
+    added
+  }
+
+  fn wake(&self) {
+    let byte = [1u8];
+    let _ = unsafe { libc::write(self.write_fd, byte.as_ptr() as *const c_void, 1) };
+  }
+}
+
+impl Drop for Shared {
+  fn drop(&mut self) {
+    unsafe { libc::close(self.write_fd) };
+  }
+}
+
+/// A live filesystem watcher.
+///
+/// Holds the debouncer alive (dropping it stops watching) and the shared queue
+/// the consumer drains. The read end of the self-pipe is handed to the caller
+/// by [`Watcher::new`] and owned by them from that point on.
+pub struct Watcher {
+  _debouncer: Box<dyn Any>,
+  shared: Arc<Shared>,
+}
+
+impl Watcher {
+  pub fn new(paths: &[String], debounce: f64, globs: &[String], only_kinds: Vec<String>) -> Result<(Self, RawFd), String> {
+    let glob_set = build_glob_set(globs)?;
+    let (read_fd, write_fd) = make_pipe()?;
+
+    let shared = Arc::new(Shared {
+      pending: Mutex::new(VecDeque::new()),
+      glob_set,
+      only_kinds,
+      write_fd,
+    });
+
+    let callback_shared = Arc::clone(&shared);
+
+    let mut debouncer = match new_debouncer(Duration::from_secs_f64(debounce), None, move |result: DebounceEventResult| {
+      if let Ok(events) = result {
+        let mut added = false;
+
+        for debounced_event in events {
+          if callback_shared.enqueue(debounced_event.event) {
+            added = true;
+          }
+        }
+
+        if added {
+          callback_shared.wake();
+        }
+      }
+    }) {
+      Ok(debouncer) => debouncer,
+
+      Err(error) => {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Failed to create watcher: {error}"));
+      }
+    };
+
+    for path in paths {
+      let watch_path = PathBuf::from(path);
+
+      if !watch_path.exists() {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Path does not exist: {}", watch_path.display()));
+      }
+
+      if let Err(error) = debouncer.watch(&watch_path, RecursiveMode::Recursive) {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Failed to watch path: {error}"));
+      }
+    }
+
+    Ok((
+      Watcher {
+        _debouncer: Box::new(debouncer),
+        shared,
+      },
+      read_fd,
+    ))
+  }
+
+  pub fn poll(&self) -> Option<(String, String)> {
+    self.shared.pending.lock().unwrap().pop_front()
+  }
+}
+
+fn make_pipe() -> Result<(RawFd, RawFd), String> {
+  let mut fds = [0 as c_int; 2];
+
+  if unsafe { libc::pipe(fds.as_mut_ptr()) } != 0 {
+    return Err("Failed to create event pipe".to_string());
+  }
+
+  set_nonblock_cloexec(fds[0]);
+  set_nonblock_cloexec(fds[1]);
+
+  Ok((fds[0], fds[1]))
+}
+
+fn set_nonblock_cloexec(fd: c_int) {
+  unsafe {
+    let flags = libc::fcntl(fd, libc::F_GETFL);
+    libc::fcntl(fd, libc::F_SETFL, flags | libc::O_NONBLOCK);
+
+    let fd_flags = libc::fcntl(fd, libc::F_GETFD);
+    libc::fcntl(fd, libc::F_SETFD, fd_flags | libc::FD_CLOEXEC);
+  }
+}
+
+fn build_glob_set(patterns: &[String]) -> Result<Option<GlobSet>, String> {
+  if patterns.is_empty() {
+    return Ok(None);
+  }
+
+  let mut builder = GlobSetBuilder::new();
+
+  for pattern in patterns {
+    let glob = Glob::new(pattern).map_err(|error| format!("Invalid glob pattern '{}': {}", pattern, error))?;
+    builder.add(glob);
+  }
+
+  let set = builder.build().map_err(|error| format!("Failed to build glob set: {}", error))?;
+
+  Ok(Some(set))
+}
+
+fn event_kind_to_string(kind: &EventKind) -> &'static str {
+  match kind {
+    EventKind::Create(CreateKind::File) => "created",
+    EventKind::Create(CreateKind::Folder) => "created",
+    EventKind::Create(_) => "created",
+    EventKind::Modify(ModifyKind::Data(_)) => "modified",
+    EventKind::Modify(ModifyKind::Name(_)) => "renamed",
+    EventKind::Modify(_) => "modified",
+    EventKind::Remove(RemoveKind::File) => "removed",
+    EventKind::Remove(RemoveKind::Folder) => "removed",
+    EventKind::Remove(_) => "removed",
+    EventKind::Access(_) => "accessed",
+    EventKind::Any | EventKind::Other => "changed",
+  }
+}

data/lib/cruise/event.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Event
+    attr_reader :path, :kind
+
+    def initialize(path, kind)
+      @path = path
+      @kind = kind
+    end
+
+    def inspect
+      "#<Cruise::Event kind=#{kind.inspect} path=#{path.inspect}>"
+    end
+
+    def to_s
+      "#{kind}: #{path}"
+    end
+  end
+end

data/lib/cruise/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cruise
-  VERSION = "0.0.0"
+  VERSION = "0.2.0"
 end

data/lib/cruise/watcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Watcher
+    def initialize(*paths, glob: nil, debounce: DEFAULT_DEBOUNCE, only: nil)
+      paths = paths.flatten.grep(String)
+
+      raise ArgumentError, "Cruise::Watcher requires at least one path" if paths.empty?
+
+      glob_patterns = glob ? Array(glob) : []
+      only_kinds = only ? Array(only).map(&:to_s) : []
+
+      initialize_native(paths, debounce.to_f, glob_patterns, only_kinds)
+    end
+
+    def io
+      raise NotImplementedError, "Cruise::Watcher#io is provided by the native extension"
+    end
+
+    def poll
+      raise NotImplementedError, "Cruise::Watcher#poll is provided by the native extension"
+    end
+
+    def close
+      raise NotImplementedError, "Cruise::Watcher#close is provided by the native extension"
+    end
+
+    private
+
+    def initialize_native(_paths, _debounce, _globs, _only_kinds)
+      raise NotImplementedError, "Cruise::Watcher#initialize_native is provided by the native extension"
+    end
+  end
+end

data/lib/cruise.rb

@@ -1,8 +1,65 @@
 # frozen_string_literal: true
 
+require "io/wait"
+
 require_relative "cruise/version"
+require_relative "cruise/event"
+require_relative "cruise/watcher"
+
+begin
+  ruby_version = RUBY_VERSION.split(".")[0..1].join(".")
+
+  begin
+    require "cruise/#{ruby_version}/cruise"
+  rescue LoadError
+    require "cruise/cruise"
+  end
+rescue LoadError => e
+  raise LoadError, "Failed to load Cruise native extension: #{e.message}"
+end
 
 module Cruise
-  class Error < StandardError; end
-  # Your code goes here...
+  DEFAULT_DEBOUNCE = 0.1
+
+  class << self
+    # Watch one or more paths and yield a Cruise::Event for each change.
+    #
+    # Blocks until interrupted. Waiting happens on the watcher's pipe via
+    # IO#wait_readable, so this releases the GVL for other threads and, when a
+    # Fiber scheduler is set (e.g. inside Async), yields to other fibers instead
+    # of blocking the reactor.
+    def watch(*paths, glob: nil, debounce: DEFAULT_DEBOUNCE, only: nil, callback: nil, &block)
+      callback = block || callback
+
+      raise ArgumentError, "Cruise.watch requires a block or callback" unless callback
+
+      watcher = Watcher.new(*paths, glob: glob, debounce: debounce, only: only)
+      io = watcher.io
+
+      begin
+        loop do
+          io.wait_readable
+          closed = drain_wakeups(io)
+
+          while (event = watcher.poll)
+            callback.call(event)
+          end
+
+          break if closed
+        end
+      ensure
+        watcher.close
+      end
+    end
+
+    private
+
+    def drain_wakeups(io)
+      loop { io.read_nonblock(4096) }
+    rescue IO::WaitReadable
+      false
+    rescue IOError
+      true
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cruise
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marco Roth
@@ -9,18 +9,33 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Cruise is a Rust-powered file system watcher with native OS integration.
-  Uses FSEvents on macOS and inotify on Linux.
+description: Cruise is a file system watcher built on native OS events. Uses FSEvents
+  on macOS and inotify on Linux.
 email:
 - marco.roth@intergga.ch
 executables: []
-extensions: []
+extensions:
+- ext/cruise/extconf.rb
 extra_rdoc_files: []
 files:
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- README.md
 - Rakefile
 - cruise.gemspec
+- ext/cruise/Cargo.toml
+- ext/cruise/build.rs
+- ext/cruise/cbindgen.toml
+- ext/cruise/cruise.c
+- ext/cruise/extconf.rb
+- ext/cruise/src/ffi.rs
+- ext/cruise/src/lib.rs
+- ext/cruise/src/watcher.rs
 - lib/cruise.rb
+- lib/cruise/event.rb
 - lib/cruise/version.rb
+- lib/cruise/watcher.rb
 homepage: https://github.com/marcoroth/cruise
 licenses:
 - MIT
@@ -38,7 +53,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -47,5 +62,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: A fast, native file watcher for Ruby
+summary: A fast, OS-native file watcher for Ruby
 test_files: []