feat(bindings/ruby): Add simple operators to Ruby binding

.github/workflows/ci_bindings_ruby.yml

@@ -42,17 +42,27 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.1", "3.2", "3.3"]
+
     env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
       BUNDLE_GEMFILE: ${{ github.workspace }}/bindings/ruby/Gemfile
+
     steps:
       - uses: actions/checkout@v4
+
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.1'
+          ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
       - name: Setup Rust toolchain
         uses: ./.github/actions/setup
-      - name: Bundle with rake
-        working-directory: "bindings/ruby"
+
+      - name: Run tests and lint
+        working-directory: bindings/ruby
         run: |
           bundle exec rake

bindings/ruby/.gitignore

@@ -4,10 +4,9 @@
 /coverage/
 /doc/
 /pkg/
-/spec/reports/
 /tmp/
+/target/
 *.bundle
 *.so
-.rspec_status
 Gemfile.lock
 Cargo.lock

bindings/ruby/.standard.yml

@@ -17,4 +17,4 @@
 
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 2.6
+ruby_version: 3.1

bindings/ruby/Cargo.toml

@@ -33,7 +33,7 @@ doc = false
 name = "opendal_ruby"
 
 [dependencies]
-magnus = { version = "0.5", features = ["bytes-crate"] }
+magnus = { version = "0.7.1", features = ["bytes"] }
 # this crate won't be published, we always use the local version
 opendal = { version = ">=0", path = "../../core", features = [
   # These are default features before v0.46. TODO: change to optional features
@@ -53,7 +53,9 @@ opendal = { version = ">=0", path = "../../core", features = [
   "services-webhdfs",
   "services-azfile",
 ] }
-rb-sys = { version = "0.9.77", default-features = false }
+rb-sys = { version = "0.9.102", default-features = false }
+# should be in sync with opendal
+bytes = "1.6"
 
 [build-dependencies]
 rb-sys-env = "0.1.2"

bindings/ruby/Gemfile

@@ -19,11 +19,15 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in opendal.gemspec
+# Includes runtime dependencies from opendal.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rake-compiler", "~> 1.2.0"
-gem "rspec", "~> 3.12.0"
-gem "standard", "~> 1.3"
-gem "rb_sys", "~> 0.9.39"
+group :development, :test do
+  gem "rake", ">= 13.0"
+  gem "rb_sys", "~> 0.9.102" # for Makefile generation in extconf.rb
+  gem "rake-compiler", "~> 1.2.0"
+  gem "minitest", "~> 5.25.0"
+  gem "minitest-reporters", "~> 1.7.1"
+  gem "activesupport", "~> 7.2.1"
+  gem "standard", "~> 1.3"
+end

bindings/ruby/README.md

@@ -17,13 +17,13 @@ bundle
 Build bindings:
 
 ```shell
-rake compile
+bundle exec rake compile
 ```
 
 Run tests:
 
 ```shell
-rake spec
+bundle exec rake spec
 ```
 
 ## License and Trademarks

bindings/ruby/Rakefile

@@ -17,18 +17,26 @@
 
 # frozen_string_literal: true
 
+require "bundler/gem_tasks"
 require "rake/testtask"
 require "rake/extensiontask"
-require "rspec/core/rake_task"
-require "bundler/gem_tasks"
 require "standard/rake"
 
-RSpec::Core::RakeTask.new(:spec)
+GEMSPEC = Gem::Specification.load("opendal.gemspec")
+CRATE_PACKAGE_NAME = "opendal-ruby"
 
-Rake::ExtensionTask.new do |ext|
+Rake::ExtensionTask.new(CRATE_PACKAGE_NAME, GEMSPEC) do |ext|
   ext.name = "opendal_ruby"
   ext.ext_dir = "."
   ext.lib_dir = "lib/opendal_ruby"
 end
 
-task default: %i[clobber compile spec standard]
+Rake::Task[:test].prerequisites << :compile
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: %i[clobber compile test standard]

bindings/ruby/extconf.rb

@@ -16,6 +16,9 @@
 # under the License.
 
 require "mkmf"
+# We use rb_sys for makefile generation only.
+# We can use `RB_SYS_CARGO_PROFILE` to choose Cargo profile
+# Read more https://github.com/oxidize-rb/rb-sys/blob/main/gem/README.md
 require "rb_sys/mkmf"
 
 create_rust_makefile("opendal_ruby/opendal_ruby")

bindings/ruby/opendal.gemspec

@@ -27,7 +27,6 @@ Gem::Specification.new do |spec|
 
   spec.summary = "OpenDAL Ruby Binding"
   spec.homepage = "https://opendal.apache.org/"
-  spec.required_ruby_version = ">= 2.6.0"
 
   spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
 
@@ -46,16 +45,19 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
   spec.extensions = ["./extconf.rb"]
 
-  # needed until rubygems supports Rust support is out of beta
-  spec.add_dependency "rb_sys", "~> 0.9.39"
-
-  # only needed when developing or packaging your gem
-  spec.add_development_dependency "rake-compiler", "~> 1.2.0"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
+  # Rubygems is a default gem that is a part of Ruby core.
+  # Rubygems 3.3.11 supports building gem with Cargo.
+  # Read more https://github.com/rubygems/rubygems/blob/master/CHANGELOG.md#3311--2022-04-07
+  #
+  # Ruby 3.1.3 includes Rubygems 3.3.26
+  # Read more https://stdgems.org/3.1.3/
+  #
+  # use a Ruby version which:
+  # - supports new Rubygems with the ability of compilation of Rust gem
+  # - not end of life
+  spec.required_ruby_version = ">= 3.1.3"
+
+  # intentionally skipping rb_sys gem because newer Rubygems will be present
 end

bindings/ruby/src/capability.rs

@@ -0,0 +1,156 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use magnus::class;
+use magnus::method;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RModule;
+
+use crate::*;
+
+// This name follows `attr_accessor` in Ruby
+macro_rules! define_accessors {
+    ($struct:ty, { $( $field:ident : $type:ty ),+ $(,)? }) => {
+        impl $struct {
+            $(
+                pub fn $field(&self) -> $type {
+                    self.0.$field
+                }
+            )+
+        }
+    };
+}
+macro_rules! bind_methods_to_ruby {
+    ($ruby_class:ident, { $( $field:ident ),+ $(,)? }) => {
+        $(
+            $ruby_class.define_method(stringify!($field), method!(Capability::$field, 0))?;
+        )+
+    };
+}
+
+/// Capability describes OpenDAL supported operations by current Operator.
+#[magnus::wrap(class = "OpenDAL::Capability", free_immediately, size)]
+pub struct Capability(ocore::Capability);
+
+impl Capability {
+    pub fn new(capability: ocore::Capability) -> Self {
+        Self(capability)
+    }
+}
+
+define_accessors!(Capability, {
+    stat: bool,
+    stat_with_if_match: bool,
+    stat_with_if_none_match: bool,
+    stat_with_override_cache_control: bool,
+    stat_with_override_content_disposition: bool,
+    stat_with_override_content_type: bool,
+    stat_with_version: bool,
+    read: bool,
+    read_with_if_match: bool,
+    read_with_if_none_match: bool,
+    read_with_override_cache_control: bool,
+    read_with_override_content_disposition: bool,
+    read_with_override_content_type: bool,
+    read_with_version: bool,
+    write: bool,
+    write_can_multi: bool,
+    write_can_empty: bool,
+    write_can_append: bool,
+    write_with_content_type: bool,
+    write_with_content_disposition: bool,
+    write_with_cache_control: bool,
+    write_with_if_none_match: bool,
+    write_with_user_metadata: bool,
+    write_multi_max_size: Option<usize>,
+    write_multi_min_size: Option<usize>,
+    write_multi_align_size: Option<usize>,
+    write_total_max_size: Option<usize>,
+    create_dir: bool,
+    delete: bool,
+    delete_with_version: bool,
+    copy: bool,
+    rename: bool,
+    list: bool,
+    list_with_limit: bool,
+    list_with_start_after: bool,
+    list_with_recursive: bool,
+    list_with_version: bool,
+    presign: bool,
+    presign_read: bool,
+    presign_stat: bool,
+    presign_write: bool,
+    batch: bool,
+    batch_delete: bool,
+    batch_max_operations: Option<usize>,
+    blocking: bool
+});
+
+// includes class into the Ruby module
+pub fn include(gem_module: &RModule) -> Result<(), Error> {
+    let class = gem_module.define_class("Capability", class::object())?;
+    bind_methods_to_ruby!(class, {
+        stat,
+        stat_with_if_match,
+        stat_with_if_none_match,
+        stat_with_override_cache_control,
+        stat_with_override_content_disposition,
+        stat_with_override_content_type,
+        stat_with_version,
+        read,
+        read_with_if_match,
+        read_with_if_none_match,
+        read_with_override_cache_control,
+        read_with_override_content_disposition,
+        read_with_override_content_type,
+        read_with_version,
+        write,
+        write_can_multi,
+        write_can_empty,
+        write_can_append,
+        write_with_content_type,
+        write_with_content_disposition,
+        write_with_cache_control,
+        write_with_if_none_match,
+        write_with_user_metadata,
+        write_multi_max_size,
+        write_multi_min_size,
+        write_multi_align_size,
+        write_total_max_size,
+        create_dir,
+        delete,
+        delete_with_version,
+        copy,
+        rename,
+        list,
+        list_with_limit,
+        list_with_start_after,
+        list_with_recursive,
+        list_with_version,
+        presign,
+        presign_read,
+        presign_stat,
+        presign_write,
+        batch,
+        batch_delete,
+        batch_max_operations,
+        blocking
+    });
+
+    Ok(())
+}