opendal 0.1.6.pre.rc.1

data/src/metadata.rs

@@ -0,0 +1,111 @@
+// 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.
+
+#![allow(
+    rustdoc::broken_intra_doc_links,
+    reason = "YARD's syntax for documentation"
+)]
+#![allow(rustdoc::invalid_html_tags, reason = "YARD's syntax for documentation")]
+#![allow(rustdoc::bare_urls, reason = "YARD's syntax for documentation")]
+
+use magnus::method;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RModule;
+
+use crate::*;
+
+/// @yard
+/// Metadata about an object.
+#[magnus::wrap(class = "OpenDal::Metadata", free_immediately, size)]
+pub struct Metadata(ocore::Metadata);
+
+impl Metadata {
+    pub fn new(metadata: ocore::Metadata) -> Self {
+        Self(metadata)
+    }
+}
+
+impl Metadata {
+    /// @yard
+    /// @def mode
+    /// The entry mode of this Metadata.
+    /// @return [String] one of `File`, `Directory`, `Unknown`.
+    ///    `Unknown` means OpenDAL doesn't have actions to the entry.
+    pub fn mode(&self) -> &str {
+        match self.0.mode() {
+            ocore::EntryMode::FILE => "File",
+            ocore::EntryMode::DIR => "Directory",
+            ocore::EntryMode::Unknown => "Unknown",
+        }
+    }
+
+    /// @yard
+    /// @def content_disposition
+    /// Content-Disposition of this object
+    /// @return [String, nil]
+    pub fn content_disposition(&self) -> Option<&str> {
+        self.0.content_disposition()
+    }
+
+    /// @yard
+    /// @def content_length
+    /// Content length of this entry.
+    /// @return [Integer]
+    pub fn content_length(&self) -> u64 {
+        self.0.content_length()
+    }
+
+    /// @yard
+    /// @def content_md5
+    /// Content MD5 of this entry.
+    /// @return [String, nil]
+    pub fn content_md5(&self) -> Option<&str> {
+        self.0.content_md5()
+    }
+
+    /// @yard
+    /// @def content_type
+    /// Content Type of this entry.
+    /// @return [String, nil]
+    pub fn content_type(&self) -> Option<&str> {
+        self.0.content_type()
+    }
+
+    /// @yard
+    /// @def etag
+    /// ETag of this entry.
+    /// @return [String, nil]
+    pub fn etag(&self) -> Option<&str> {
+        self.0.etag()
+    }
+}
+
+pub fn include(ruby: &Ruby, gem_module: &RModule) -> Result<(), Error> {
+    let class = gem_module.define_class("Metadata", ruby.class_object())?;
+    class.define_method("mode", method!(Metadata::mode, 0))?;
+    class.define_method(
+        "content_disposition",
+        method!(Metadata::content_disposition, 0),
+    )?;
+    class.define_method("content_length", method!(Metadata::content_length, 0))?;
+    class.define_method("content_md5", method!(Metadata::content_md5, 0))?;
+    class.define_method("content_type", method!(Metadata::content_type, 0))?;
+    class.define_method("etag", method!(Metadata::etag, 0))?;
+
+    Ok(())
+}

data/src/middlewares.rs

@@ -0,0 +1,174 @@
+// 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 std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+
+use magnus::method;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RModule;
+use magnus::Ruby;
+
+use opendal::raw::Accessor as OCoreAccessor;
+use opendal::raw::Layer as OCoreLayer;
+
+use crate::operator::Operator;
+use crate::*;
+
+// Applies an OpenDAL layer (treated as middleware in Ruby).
+//
+// Magnus provides `TypedData` and the `magnus::wrap` macro for strong typing between Ruby and Rust,
+// but we avoid exposing Rust types directly in Ruby to allow packaging layers in separate gems.
+//
+// Instead, we rely on duck typing: each Ruby-defined layer must implement `#apply_to(operator)`.
+// This internal function helps apply a Rust layer by locking the inner Layer and wrapping the result
+// back into an `Operator`.
+fn apply_layer<T>(
+    ruby: &Ruby,
+    inner: &Arc<Mutex<T>>,
+    operator: &Operator,
+    name: &'static str,
+) -> Result<Operator, Error>
+where
+    T: OCoreLayer<OCoreAccessor> + Clone + Send + Sync + 'static,
+{
+    let guard = inner.lock().map_err(|_| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("poisoned {name} mutex"),
+        )
+    })?;
+
+    let layered = operator.async_op.clone().layer(guard.clone());
+
+    Ok(Operator::from_operator(layered))
+}
+
+/// @yard
+/// Adds retry for temporary failed operations.
+///
+/// See [`opendal::layers::RetryLayer`] for more information.
+#[magnus::wrap(class = "OpenDal::Middleware::Retry")]
+struct RetryMiddleware(Arc<Mutex<ocore::layers::RetryLayer>>);
+
+impl RetryMiddleware {
+    fn new() -> Self {
+        Self(Arc::new(Mutex::new(ocore::layers::RetryLayer::default())))
+    }
+
+    fn apply_to(ruby: &Ruby, rb_self: &Self, operator: &Operator) -> Result<Operator, Error> {
+        apply_layer(ruby, &rb_self.0, operator, "OpenDal::Middleware::Retry")
+    }
+}
+
+/// @yard
+/// Adds concurrent request limit.
+///
+/// See [`opendal::layers::ConcurrentLimitLayer`] for more information.
+#[magnus::wrap(class = "OpenDal::Middleware::ConcurrentLimit")]
+struct ConcurrentLimitMiddleware(Arc<Mutex<ocore::layers::ConcurrentLimitLayer>>);
+
+impl ConcurrentLimitMiddleware {
+    fn new(permits: usize) -> Self {
+        Self(Arc::new(Mutex::new(
+            ocore::layers::ConcurrentLimitLayer::new(permits),
+        )))
+    }
+
+    fn apply_to(ruby: &Ruby, rb_self: &Self, operator: &Operator) -> Result<Operator, Error> {
+        apply_layer(
+            ruby,
+            &rb_self.0,
+            operator,
+            "OpenDal::Middleware::ConcurrentLimit",
+        )
+    }
+}
+
+/// @yard
+/// Adds a bandwidth rate limiter to the underlying services.
+///
+/// See [`opendal::layers::ThrottleLayer`] for more information.
+#[magnus::wrap(class = "OpenDal::Middleware::Throttle")]
+struct ThrottleMiddleware(Arc<Mutex<ocore::layers::ThrottleLayer>>);
+
+impl ThrottleMiddleware {
+    fn new(bandwidth: u32, burst: u32) -> Self {
+        Self(Arc::new(Mutex::new(ocore::layers::ThrottleLayer::new(
+            bandwidth, burst,
+        ))))
+    }
+
+    fn apply_to(ruby: &Ruby, rb_self: &Self, operator: &Operator) -> Result<Operator, Error> {
+        apply_layer(ruby, &rb_self.0, operator, "OpenDal::Middleware::Throttle")
+    }
+}
+
+fn parse_duration(ruby: &Ruby, val: f64) -> Result<Duration, Error> {
+    Duration::try_from_secs_f64(val).map_err(|e| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("invalid float duration: {e}"),
+        )
+    })
+}
+
+/// @yard
+/// Adds timeout for every operation to avoid slow or unexpected hang operations.
+///
+/// See [`opendal::layers::TimeoutLayer`] for more information.
+#[magnus::wrap(class = "OpenDal::Middleware::Timeout")]
+struct TimeoutMiddleware(Arc<Mutex<ocore::layers::TimeoutLayer>>);
+
+impl TimeoutMiddleware {
+    fn new(ruby: &Ruby, timeout: f64, io_timeout: f64) -> Result<Self, Error> {
+        let layer = ocore::layers::TimeoutLayer::new()
+            .with_timeout(parse_duration(ruby, timeout)?)
+            .with_io_timeout(parse_duration(ruby, io_timeout)?);
+        Ok(Self(Arc::new(Mutex::new(layer))))
+    }
+
+    fn apply_to(ruby: &Ruby, rb_self: &Self, operator: &Operator) -> Result<Operator, Error> {
+        apply_layer(ruby, &rb_self.0, operator, "OpenDal::Middleware::Timeout")
+    }
+}
+
+pub fn include(ruby: &Ruby, middleware_module: &RModule) -> Result<(), Error> {
+    middleware_module.define_class("Retry", ruby.class_object())?;
+
+    let retry = middleware_module.define_class("Retry", ruby.class_object())?;
+    retry.define_singleton_method("new", function!(RetryMiddleware::new, 0))?;
+    retry.define_method("apply_to", method!(RetryMiddleware::apply_to, 1))?;
+
+    let concurrent_limit =
+        middleware_module.define_class("ConcurrentLimit", ruby.class_object())?;
+    concurrent_limit
+        .define_singleton_method("new", function!(ConcurrentLimitMiddleware::new, 1))?;
+    concurrent_limit.define_method("apply_to", method!(ConcurrentLimitMiddleware::apply_to, 1))?;
+
+    let throttle_middleware = middleware_module.define_class("Throttle", ruby.class_object())?;
+    throttle_middleware.define_singleton_method("new", function!(ThrottleMiddleware::new, 2))?;
+    throttle_middleware.define_method("apply_to", method!(ThrottleMiddleware::apply_to, 1))?;
+
+    let timeout_middleware = middleware_module.define_class("Timeout", ruby.class_object())?;
+    timeout_middleware.define_singleton_method("new", function!(TimeoutMiddleware::new, 2))?;
+    timeout_middleware.define_method("apply_to", method!(TimeoutMiddleware::apply_to, 1))?;
+
+    Ok(())
+}

data/src/operator.rs

@@ -0,0 +1,310 @@
+// 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.
+
+#![allow(
+    rustdoc::broken_intra_doc_links,
+    reason = "YARD's syntax for documentation"
+)]
+#![allow(rustdoc::invalid_html_tags, reason = "YARD's syntax for documentation")]
+#![allow(rustdoc::bare_urls, reason = "YARD's syntax for documentation")]
+
+use std::collections::HashMap;
+use std::str::FromStr;
+
+use magnus::method;
+use magnus::prelude::*;
+use magnus::scan_args::get_kwargs;
+use magnus::scan_args::scan_args;
+use magnus::Error;
+use magnus::RHash;
+use magnus::RModule;
+use magnus::RString;
+use magnus::Ruby;
+use magnus::Value;
+
+use crate::capability::Capability;
+use crate::io::Io;
+use crate::lister::Lister;
+use crate::metadata::Metadata;
+use crate::operator_info::OperatorInfo;
+use crate::*;
+
+/// @yard
+/// The entrypoint for operating with file services and files.
+#[magnus::wrap(class = "OpenDal::Operator", free_immediately, size)]
+pub struct Operator {
+    // We keep a reference to an `Operator` because:
+    // 1. Some builder functions exist only with the `Operator` struct.
+    // 2. Some builder functions don't exist in the `BlockingOperator`, e.g., `Operator::layer`, builder methods.
+    //
+    // We don't support async because:
+    // 1. Ractor and async is not stable.
+    // 2. magnus doesn't release GVL lock during operations yet.
+    // 3. Majority of use cases are still blocking.
+    //
+    // In practice, we will not use operator directly because of the async support.
+    pub async_op: ocore::Operator,
+    // The cached blocking operator coming from `Operator::blocking`.
+    // Important to keep in sync after making changes to the `Operator`.
+    //
+    // We declare this `BlockingOperator` to state the intent of assumptions instead of
+    // getting a `BlockingOperator` for an operation dynamically every time.
+    pub blocking_op: ocore::blocking::Operator,
+}
+
+impl Operator {
+    // Convenience helper to construct operator
+    #[inline]
+    pub(crate) fn from_operator(operator: ocore::Operator) -> Operator {
+        let handle = RUNTIME.handle();
+        let _enter = handle.enter();
+        let blocking_op = ocore::blocking::Operator::new(operator.clone())
+            .expect("initiate blocking operator must succeed");
+
+        Operator {
+            async_op: operator,
+            blocking_op,
+        }
+    }
+}
+
+impl Operator {
+    fn new(
+        ruby: &Ruby,
+        scheme: String,
+        options: Option<HashMap<String, String>>,
+    ) -> Result<Self, Error> {
+        let scheme = ocore::Scheme::from_str(&scheme)
+            .map_err(|err| {
+                ocore::Error::new(ocore::ErrorKind::Unexpected, "unsupported scheme")
+                    .set_source(err)
+            })
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+        let options = options.unwrap_or_default();
+
+        let op = ocore::Operator::via_iter(scheme, options)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+
+        Ok(Operator::from_operator(op))
+    }
+
+    /// @yard
+    /// @def read(path)
+    /// Reads the whole path into string.
+    /// @param path [String]
+    /// @return [String]
+    fn read(ruby: &Ruby, rb_self: &Self, path: String) -> Result<bytes::Bytes, Error> {
+        let buffer = rb_self
+            .blocking_op
+            .read(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+        Ok(buffer.to_bytes())
+    }
+
+    /// @yard
+    /// @def write(path, buffer)
+    /// Writes string into given path.
+    /// @param path [String]
+    /// @param buffer [String]
+    /// @return [nil]
+    fn write(ruby: &Ruby, rb_self: &Self, path: String, bs: RString) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .write(&path, bs.to_bytes())
+            .map(|_| ())
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def read(path)
+    /// Gets current path's metadata **without cache** directly.
+    /// @param path
+    /// @return [Metadata]
+    fn stat(ruby: &Ruby, rb_self: &Self, path: String) -> Result<Metadata, Error> {
+        rb_self
+            .blocking_op
+            .stat(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+            .map(Metadata::new)
+    }
+
+    /// @yard
+    /// @def capability
+    /// Gets capabilities of the current operator
+    /// @return [Capability]
+    fn capability(&self) -> Result<Capability, Error> {
+        let capability = self.blocking_op.info().full_capability();
+        Ok(Capability::new(capability))
+    }
+
+    /// @yard
+    /// @def create_dir(path)
+    /// Creates directory recursively similar as `mkdir -p`
+    /// The ending path must be `/`. Otherwise, OpenDAL throws `NotADirectory` error.
+    /// @param path [String]
+    /// @return [nil]
+    fn create_dir(ruby: &Ruby, rb_self: &Self, path: String) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .create_dir(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def delete(path)
+    /// Deletes given path
+    /// @param path [String]
+    /// @return [nil]
+    fn delete(ruby: &Ruby, rb_self: &Self, path: String) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .delete(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def exist?(path)
+    /// Returns if this path exists
+    /// @param path [String]
+    /// @return [Boolean]
+    fn exists(ruby: &Ruby, rb_self: &Self, path: String) -> Result<bool, Error> {
+        rb_self
+            .blocking_op
+            .exists(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def rename(from, to)
+    /// Renames a file from `from` to `to`
+    /// @param from [String] a file path
+    /// @param to [String] a file path
+    /// @return [nil]
+    fn rename(ruby: &Ruby, rb_self: &Self, from: String, to: String) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .rename(&from, &to)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def remove_all(path)
+    /// Removes the path and all nested directories and files recursively
+    /// @param path [String]
+    /// @return [nil]
+    fn remove_all(ruby: &Ruby, rb_self: &Self, path: String) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .remove_all(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def copy(from, to)
+    /// Copies a file from `from` to `to`.
+    /// @param from [String] a file path
+    /// @param to [String] a file path
+    /// @return [nil]
+    fn copy(ruby: &Ruby, rb_self: &Self, from: String, to: String) -> Result<(), Error> {
+        rb_self
+            .blocking_op
+            .copy(&from, &to)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))
+    }
+
+    /// @yard
+    /// @def open(path, mode)
+    /// Opens a `IO`-like reader for the given path.
+    /// @param path [String] file path
+    /// @param mode [String] operation mode, e.g., `r`, `w`, or `rb`.
+    /// @raise [ArgumentError] invalid mode, or when the mode is not unique
+    /// @return [OpenDal::IO]
+    fn open(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Io, Error> {
+        let args = scan_args::<(String,), (Option<Value>, Option<Value>), (), (), RHash, ()>(args)?;
+        let (path,) = args.required;
+        let (option_mode, option_permission) = args.optional;
+        let kwargs = args.keywords;
+
+        // Ruby handles Qnil safely (will not assign to Qnil)
+        let mode = option_mode.unwrap_or(ruby.str_new("r").as_value());
+        let permission = option_permission.unwrap_or(ruby.qnil().as_value());
+
+        let operator = rb_self.blocking_op.clone();
+        Io::new(ruby, operator, path, mode, permission, kwargs)
+    }
+
+    /// @yard
+    /// @def list(limit: nil, start_after: nil, recursive: nil)
+    /// Lists the directory.
+    /// @param limit [usize, nil] per-request max results
+    /// @param start_after [String, nil] the specified key to start listing from.
+    /// @param recursive [Boolean, nil] lists the directory recursively.
+    /// @return [Lister]
+    pub fn list(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Lister, Error> {
+        let args = scan_args::<(String,), (), (), (), _, ()>(args)?;
+        let (path,) = args.required;
+        let kwargs = get_kwargs::<_, (), (Option<usize>, Option<String>, Option<bool>), ()>(
+            args.keywords,
+            &[],
+            &["limit", "start_after", "recursive"],
+        )?;
+        let (limit, start_after, recursive) = kwargs.optional;
+
+        let lister = rb_self
+            .blocking_op
+            .lister_options(
+                &path,
+                ocore::options::ListOptions {
+                    limit,
+                    start_after,
+                    recursive: recursive.unwrap_or(false),
+                    ..Default::default()
+                },
+            )
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+
+        Ok(Lister::new(lister))
+    }
+
+    /// @yard
+    /// @def info
+    /// Gets meta information of the underlying accessor.
+    /// @return [OperatorInfo]
+    fn info(&self) -> Result<OperatorInfo, Error> {
+        Ok(OperatorInfo(self.blocking_op.info()))
+    }
+}
+
+pub fn include(ruby: &Ruby, gem_module: &RModule) -> Result<(), Error> {
+    let class = gem_module.define_class("Operator", ruby.class_object())?;
+    class.define_singleton_method("new", function!(Operator::new, 2))?;
+    class.define_method("read", method!(Operator::read, 1))?;
+    class.define_method("write", method!(Operator::write, 2))?;
+    class.define_method("stat", method!(Operator::stat, 1))?;
+    class.define_method("capability", method!(Operator::capability, 0))?;
+    class.define_method("create_dir", method!(Operator::create_dir, 1))?;
+    class.define_method("delete", method!(Operator::delete, 1))?;
+    class.define_method("exist?", method!(Operator::exists, 1))?;
+    class.define_method("rename", method!(Operator::rename, 2))?;
+    class.define_method("remove_all", method!(Operator::remove_all, 1))?;
+    class.define_method("copy", method!(Operator::copy, 2))?;
+    class.define_method("open", method!(Operator::open, -1))?;
+    class.define_method("list", method!(Operator::list, -1))?;
+    class.define_method("info", method!(Operator::info, 0))?;
+
+    Ok(())
+}

data/src/operator_info.rs

@@ -0,0 +1,83 @@
+// 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.
+
+#![allow(
+    rustdoc::broken_intra_doc_links,
+    reason = "YARD's syntax for documentation"
+)]
+
+use magnus::method;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RModule;
+
+use crate::capability::Capability;
+use crate::*;
+
+/// Metadata for operator, users can use this metadata to get information of operator.
+#[magnus::wrap(class = "OpenDal::OperatorInfo", free_immediately, size)]
+pub struct OperatorInfo(pub ocore::OperatorInfo);
+
+impl OperatorInfo {
+    /// @yard
+    /// @def scheme
+    /// Returns the scheme string of the operator.
+    /// @return [String]
+    pub fn scheme(&self) -> &str {
+        self.0.scheme().into()
+    }
+
+    /// @yard
+    /// @def root
+    /// Returns the root path of the operator, will be in format like `/path/to/dir/`
+    /// @return [String]
+    pub fn root(&self) -> String {
+        self.0.root()
+    }
+
+    /// @yard
+    /// @def name
+    /// Returns the name of backend, could be empty if underlying backend doesn't have namespace concept.
+    ///
+    /// For example:
+    ///
+    /// - name for `s3` => bucket name
+    /// - name for `azblob` => container name
+    ///
+    /// @return [String]
+    pub fn name(&self) -> String {
+        self.0.name()
+    }
+
+    /// @yard
+    /// @def capability
+    /// Returns the [`Full Capability`] of the operator.
+    /// @return [Capability]
+    pub fn capability(&self) -> Capability {
+        Capability::new(self.0.full_capability())
+    }
+}
+
+pub fn include(ruby: &Ruby, gem_module: &RModule) -> Result<(), Error> {
+    let class = gem_module.define_class("OperatorInfo", ruby.class_object())?;
+    class.define_method("scheme", method!(OperatorInfo::scheme, 0))?;
+    class.define_method("root", method!(OperatorInfo::root, 0))?;
+    class.define_method("name", method!(OperatorInfo::name, 0))?;
+    class.define_method("capability", method!(OperatorInfo::capability, 0))?;
+
+    Ok(())
+}