opendal 0.1.11 → 0.1.13

data/core/services/goosefs/src/backend.rs

@@ -64,13 +64,11 @@ impl GoosefsBuilder {
     /// Single master: `"10.0.0.1:9200"`
     /// HA (comma-separated): `"10.0.0.1:9200,10.0.0.2:9200,10.0.0.3:9200"`
     ///
-    /// When provided here it **overrides** any address discovered from
-    /// `goosefs-site.properties` or `GOOSEFS_MASTER_ADDR`. When left unset
-    /// the builder falls back to the SDK's auto-discovery chain
-    /// (defaults → properties → env) — see
-    /// [goosefs-sdk `docs/CLIENT_CONFIGURATION.md`](https://github.com/Tencent/tencent-goosefs-rust-sdk/blob/main/docs/CLIENT_CONFIGURATION.md)
-    /// §1. `build()` fails with `ConfigInvalid` only if **no** source
-    /// supplies a master address.
+    /// This is the lowest-priority source: `build()` uses it only when
+    /// neither `GOOSEFS_MASTER_ADDR` nor `goosefs-site.properties` declares a
+    /// master address, and fails with `ConfigInvalid` when no source supplies
+    /// one. See [`crate::GoosefsConfig::master_addr`] for the full resolution
+    /// order and its rationale.
     pub fn master_addr(mut self, addr: &str) -> Self {
         if !addr.is_empty() {
             self.config.master_addr = Some(addr.to_string());
@@ -124,6 +122,160 @@ impl GoosefsBuilder {
     }
 }
 
+/// The source that supplied the master addresses of an auto-loaded SDK config.
+///
+/// `goosefs_sdk::config::GoosefsConfig::from_properties_auto()` always returns
+/// a master address: when neither `GOOSEFS_MASTER_ADDR` nor
+/// `goosefs-site.properties` declares one, it keeps the SDK default
+/// `127.0.0.1:9200`. The loaded value therefore cannot tell "a real source
+/// configured this" from "nothing configured this", and the builder has to
+/// ask which source actually spoke.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum MasterAddrSource {
+    /// `GOOSEFS_MASTER_ADDR` supplied the addresses.
+    Env,
+    /// `goosefs-site.properties` declared `goosefs.master.rpc.addresses` or
+    /// `goosefs.master.hostname`.
+    SiteProperties,
+    /// Neither spoke; the loaded addresses are the SDK defaults.
+    Unset,
+}
+
+/// Apply the master-address resolution order to an auto-loaded SDK config.
+///
+/// `goosefs-site.properties` carries a deployment's whole HA master list,
+/// which a URI authority such as `goosefs://host:9200/path` cannot express, so
+/// a site file that declares masters outranks `explicit` (the `master_addr`
+/// config key, whether it arrived from the builder, the option map, or the URI
+/// authority). `GOOSEFS_MASTER_ADDR` stays on top as the per-process override:
+///
+/// ```text
+/// GOOSEFS_MASTER_ADDR  >  goosefs-site.properties  >  master_addr
+/// ```
+///
+/// `from_properties_auto()` already resolved the first two sources, so
+/// `explicit` is written into `config` only when neither spoke. Returns
+/// `ConfigInvalid` when `explicit` holds no address after trimming, and when
+/// no source at all supplies one.
+fn apply_master_addr_precedence(
+    config: &mut goosefs_sdk::config::GoosefsConfig,
+    explicit: Option<&str>,
+) -> Result<()> {
+    let explicit_addrs = match explicit {
+        Some(master_addr) => {
+            let addrs: Vec<String> = master_addr
+                .split(',')
+                .map(|s| s.trim().to_string())
+                .filter(|s| !s.is_empty())
+                .collect();
+            if addrs.is_empty() {
+                return Err(Error::new(
+                    ErrorKind::ConfigInvalid,
+                    "master_addr is empty after trimming",
+                )
+                .with_operation("Builder::build")
+                .with_context("service", GOOSEFS_SCHEME));
+            }
+            Some(addrs)
+        }
+        None => None,
+    };
+
+    match detect_master_addr_source() {
+        MasterAddrSource::Unset => {
+            let Some(addrs) = explicit_addrs else {
+                return Err(Error::new(
+                    ErrorKind::ConfigInvalid,
+                    "master_addr is not configured: set it via GoosefsBuilder::master_addr(...), \
+                     the `master_addr` config key, the GOOSEFS_MASTER_ADDR env var, \
+                     or `goosefs.master.hostname`/`goosefs.master.rpc.addresses` in goosefs-site.properties",
+                )
+                .with_operation("Builder::build")
+                .with_context("service", GOOSEFS_SCHEME));
+            };
+
+            config.master_addr = addrs[0].clone();
+            config.master_addrs = if addrs.len() > 1 { addrs } else { Vec::new() };
+        }
+        source => {
+            if let Some(addrs) = explicit_addrs {
+                debug!(
+                    "GoosefsBuilder ignores master_addr {addrs:?}: {source:?} supplies {} (addrs={:?})",
+                    config.master_addr, config.master_addrs
+                );
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Report which source supplied the master addresses that
+/// `from_properties_auto()` loaded.
+fn detect_master_addr_source() -> MasterAddrSource {
+    // Probe `GOOSEFS_MASTER_ADDR` through the SDK's own parser so that the
+    // `gfs://h1:9200,h2:9200/root` URI form and the bare comma list are
+    // recognised exactly as `from_properties_auto()` recognises them. Blanking
+    // the address first makes an unset, empty, or malformed value observable:
+    // in those cases `apply_env()` leaves the field untouched.
+    let probe = goosefs_sdk::config::GoosefsConfig {
+        master_addr: String::new(),
+        master_addrs: Vec::new(),
+        ..Default::default()
+    }
+    .apply_env();
+    if !probe.master_addr.is_empty() || !probe.master_addrs.is_empty() {
+        return MasterAddrSource::Env;
+    }
+
+    // The SDK searches `$GOOSEFS_CONFIG_FILE`, `$GOOSEFS_CONF_DIR`,
+    // `$GOOSEFS_HOME/conf`, `~/.goosefs`, and `/etc/goosefs` for
+    // `goosefs-site.properties`. An unreadable file is left to
+    // `from_properties_auto()`, which already failed the build above.
+    if let Some(path) = goosefs_sdk::config::discover_config_file()
+        && let Ok(content) = std::fs::read_to_string(&path)
+        && site_properties_declare_master(&content)
+    {
+        return MasterAddrSource::SiteProperties;
+    }
+
+    MasterAddrSource::Unset
+}
+
+/// Report whether `goosefs-site.properties` declares a master address.
+///
+/// The SDK's properties parser is private, so key lookup repeats its
+/// documented Java `Properties.load()` rules here: `#` and `!` start a comment
+/// line, the first `=` (else the first `:`) separates key from value, and the
+/// last assignment of a key wins. `goosefs.master.rpc.addresses` shadows
+/// `goosefs.master.hostname` whenever it is present, matching the order in
+/// which the SDK consults the two keys.
+fn site_properties_declare_master(content: &str) -> bool {
+    let mut addresses = None;
+    let mut hostname = None;
+
+    for line in content.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') || line.starts_with('!') {
+            continue;
+        }
+        let Some(sep) = line.find('=').or_else(|| line.find(':')) else {
+            continue;
+        };
+
+        match line[..sep].trim() {
+            "goosefs.master.rpc.addresses" => addresses = Some(line[sep + 1..].trim()),
+            "goosefs.master.hostname" => hostname = Some(line[sep + 1..].trim()),
+            _ => {}
+        }
+    }
+
+    match addresses {
+        Some(addresses) => addresses.split(',').any(|addr| !addr.trim().is_empty()),
+        None => hostname.is_some_and(|hostname| !hostname.is_empty()),
+    }
+}
+
 impl Builder for GoosefsBuilder {
     type Config = GoosefsConfig;
 
@@ -156,8 +308,9 @@ impl Builder for GoosefsBuilder {
         //   * properties file present but malformed → hard-fail
         //     (broken config must not be silently dropped)
         //
-        // Builder-explicit fields (Step 2) have the final say, overriding
-        // anything discovered from properties / env.
+        // Builder-explicit fields overlay this config afterwards. The master
+        // address is the one exception: Step 2 keeps the properties/env value
+        // on top, see `apply_master_addr_precedence`.
         let mut goosefs_config = goosefs_sdk::config::GoosefsConfig::from_properties_auto()
             .map_err(|e| {
                 Error::new(
@@ -171,50 +324,15 @@ impl Builder for GoosefsBuilder {
         // Root always comes from OpenDAL (it's an OpenDAL-layer concept).
         goosefs_config.root = root.clone();
 
-        // ── Step 2: overlay builder-explicit fields (authoritative) ───────────
-        if let Some(ref master_addr) = self.config.master_addr {
-            let addrs: Vec<String> = master_addr
-                .split(',')
-                .map(|s| s.trim().to_string())
-                .filter(|s| !s.is_empty())
-                .collect();
-
-            if addrs.is_empty() {
-                return Err(Error::new(
-                    ErrorKind::ConfigInvalid,
-                    "master_addr is empty after trimming",
-                )
-                .with_operation("Builder::build")
-                .with_context("service", GOOSEFS_SCHEME));
-            }
-
-            if addrs.len() == 1 {
-                goosefs_config.master_addr = addrs[0].clone();
-                goosefs_config.master_addrs = Vec::new();
-            } else {
-                goosefs_config.master_addr = addrs[0].clone();
-                goosefs_config.master_addrs = addrs;
-            }
-        }
-
-        // After properties/env auto-load + builder overlay, we must still
-        // have at least one usable master address. If we don't, fail fast
-        // with a message that points the user at all three sources.
-        if goosefs_config.master_addr.is_empty() && goosefs_config.master_addrs.is_empty() {
-            return Err(Error::new(
-                ErrorKind::ConfigInvalid,
-                "master_addr is not configured: set it via GoosefsBuilder::master_addr(...), \
-                 the `master_addr` config key, the GOOSEFS_MASTER_ADDR env var, \
-                 or `goosefs.master.hostname`/`goosefs.master.rpc.addresses` in goosefs-site.properties",
-            )
-            .with_operation("Builder::build")
-            .with_context("service", GOOSEFS_SCHEME));
-        }
+        // ── Step 2: resolve the master address ────────────────────────────────
+        apply_master_addr_precedence(&mut goosefs_config, self.config.master_addr.as_deref())?;
         debug!(
             "GoosefsBuilder use master_addr {} (addrs={:?})",
             goosefs_config.master_addr, goosefs_config.master_addrs
         );
 
+        // ── Step 3: overlay the remaining builder-explicit fields ─────────────
+
         if let Some(block_size) = self.config.block_size {
             goosefs_config.block_size = block_size;
         }
@@ -258,7 +376,7 @@ impl Builder for GoosefsBuilder {
             goosefs_config = goosefs_config.with_auth_username(auth_username);
         }
 
-        // ── Step 3: validate the final merged config ──────────────────────────
+        // ── Step 4: validate the final merged config ──────────────────────────
         goosefs_config.validate().map_err(|e| {
             Error::new(
                 ErrorKind::ConfigInvalid,
@@ -411,9 +529,215 @@ impl Service for GoosefsBackend {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use goosefs_sdk::config::ENV_CONF_DIR;
+    use goosefs_sdk::config::ENV_CONFIG_FILE;
+    use goosefs_sdk::config::ENV_HOME;
+    use goosefs_sdk::config::ENV_MASTER_ADDR;
+    use std::path::PathBuf;
+    use std::sync::Mutex;
+
+    /// `GOOSEFS_*` vars are process-global; serialize every test that
+    /// exercises master-address resolution through them.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    const SITE_HA: &str =
+        "goosefs.master.rpc.addresses=172.31.5.10:9200,172.31.5.2:9200,172.31.5.11:9200\n";
+    const SITE_NO_MASTER: &str = "goosefs.user.block.size.bytes.default=4MB\n";
+
+    /// Write a `goosefs-site.properties` fixture, point `$GOOSEFS_CONFIG_FILE`
+    /// at it, and clear the other resolution inputs.
+    ///
+    /// A file is written even for the "no master keys" cases so that discovery
+    /// stops at `$GOOSEFS_CONFIG_FILE` instead of reaching a `~/.goosefs` or
+    /// `/etc/goosefs` file that happens to exist on the host.
+    fn site_properties(name: &str, content: &str) -> PathBuf {
+        let path = std::env::temp_dir().join(format!(
+            "opendal_goosefs_{}_{name}_site.properties",
+            std::process::id()
+        ));
+        std::fs::write(&path, content).expect("write goosefs-site.properties");
+
+        unsafe {
+            std::env::set_var(ENV_CONFIG_FILE, &path);
+            std::env::remove_var(ENV_CONF_DIR);
+            std::env::remove_var(ENV_HOME);
+            std::env::remove_var(ENV_MASTER_ADDR);
+        }
+
+        path
+    }
+
+    fn clear_site_properties(path: &PathBuf) {
+        unsafe {
+            std::env::remove_var(ENV_CONFIG_FILE);
+            std::env::remove_var(ENV_MASTER_ADDR);
+        }
+        let _ = std::fs::remove_file(path);
+    }
+
+    /// Resolve master addresses exactly as `build()` does: auto-load, then
+    /// apply the precedence.
+    fn resolve(explicit: Option<&str>) -> Result<(String, Vec<String>)> {
+        let mut config = goosefs_sdk::config::GoosefsConfig::from_properties_auto()
+            .expect("auto-load must succeed");
+        apply_master_addr_precedence(&mut config, explicit)?;
+        Ok((config.master_addr, config.master_addrs))
+    }
+
+    /// A site file that declares `goosefs.master.rpc.addresses` supplies the
+    /// HA list even when the URI authority carries an unreachable address.
+    ///
+    /// This is the reported failure: with `GOOSEFS_CONFIG_FILE` pointing at a
+    /// file that lists the real masters, the client still dialed the dummy
+    /// address from `goosefs://192.0.2.5:9999/...`.
+    #[test]
+    fn site_properties_outrank_uri_authority() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("site_over_uri", SITE_HA);
+
+        let (master_addr, master_addrs) =
+            resolve(Some("192.0.2.5:9999")).expect("resolution must succeed");
+
+        assert_eq!(master_addr, "172.31.5.10:9200");
+        assert_eq!(
+            master_addrs,
+            vec![
+                "172.31.5.10:9200".to_string(),
+                "172.31.5.2:9200".to_string(),
+                "172.31.5.11:9200".to_string(),
+            ]
+        );
+
+        clear_site_properties(&path);
+    }
+
+    /// Without a URI authority or `GOOSEFS_MASTER_ADDR`, a declared site file
+    /// still supplies the masters — `goosefs:///path` must not be rejected for
+    /// a missing host.
+    #[test]
+    fn site_properties_resolve_without_explicit_addr() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("site_only", SITE_HA);
+
+        let (master_addr, master_addrs) = resolve(None).expect("resolution must succeed");
+
+        assert_eq!(master_addr, "172.31.5.10:9200");
+        assert_eq!(master_addrs.len(), 3);
+
+        clear_site_properties(&path);
+    }
+
+    /// `GOOSEFS_MASTER_ADDR` is the per-process override and outranks both the
+    /// site file and the URI authority.
+    #[test]
+    fn env_master_addr_outranks_site_properties_and_uri_authority() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("env_over_site", SITE_HA);
+        unsafe { std::env::set_var(ENV_MASTER_ADDR, "10.0.0.7:9200") };
+
+        let (master_addr, master_addrs) =
+            resolve(Some("192.0.2.5:9999")).expect("resolution must succeed");
+
+        assert_eq!(master_addr, "10.0.0.7:9200");
+        assert!(
+            master_addrs.is_empty(),
+            "a single env address must not populate the HA list, got {master_addrs:?}"
+        );
+
+        clear_site_properties(&path);
+    }
+
+    /// A site file without master keys leaves `master_addr` in charge, so a
+    /// URI authority or option-map address is used as before.
+    #[test]
+    fn explicit_addr_applies_when_no_source_declares_masters() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("explicit_only", SITE_NO_MASTER);
+
+        let (master_addr, master_addrs) =
+            resolve(Some("10.0.0.1:9200,10.0.0.2:9200")).expect("resolution must succeed");
+
+        assert_eq!(master_addr, "10.0.0.1:9200");
+        assert_eq!(
+            master_addrs,
+            vec!["10.0.0.1:9200".to_string(), "10.0.0.2:9200".to_string()]
+        );
+
+        clear_site_properties(&path);
+    }
+
+    /// When no source declares a master address, `build()` must fail instead
+    /// of silently dialing the SDK default `127.0.0.1:9200`.
+    #[test]
+    fn missing_master_addr_fails() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("missing_master", SITE_NO_MASTER);
+
+        let err = resolve(None).expect_err("resolution must fail without any master address");
+        assert_eq!(err.kind(), ErrorKind::ConfigInvalid);
+        assert!(
+            err.to_string().contains("master_addr is not configured"),
+            "unexpected error message: {err}"
+        );
+
+        clear_site_properties(&path);
+    }
+
+    /// `GOOSEFS_MASTER_ADDR` also accepts the SDK's `gfs://` URI form, and
+    /// resolution must recognise it as a real source rather than falling
+    /// through to `master_addr`.
+    #[test]
+    fn env_master_addr_accepts_gfs_uri_form() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let path = site_properties("env_gfs_uri", SITE_NO_MASTER);
+        unsafe { std::env::set_var(ENV_MASTER_ADDR, "gfs://10.0.0.1:9200,10.0.0.2:9200/lance") };
+
+        let (master_addr, master_addrs) =
+            resolve(Some("192.0.2.5:9999")).expect("resolution must succeed");
+
+        assert_eq!(master_addr, "10.0.0.1:9200");
+        assert_eq!(master_addrs.len(), 2);
+
+        clear_site_properties(&path);
+    }
+
+    #[test]
+    fn site_properties_declare_master_reads_both_keys() {
+        assert!(site_properties_declare_master(
+            "goosefs.master.rpc.addresses=10.0.0.1:9200,10.0.0.2:9200\n"
+        ));
+        assert!(site_properties_declare_master(
+            "goosefs.master.hostname = master-1\ngoosefs.master.rpc.port=9200\n"
+        ));
+        // Java `Properties.load()` also accepts `:` as the separator.
+        assert!(site_properties_declare_master(
+            "goosefs.master.hostname:master-1\n"
+        ));
+    }
+
+    #[test]
+    fn site_properties_declare_master_rejects_absent_and_blank_keys() {
+        assert!(!site_properties_declare_master(SITE_NO_MASTER));
+        assert!(!site_properties_declare_master(
+            "# goosefs.master.rpc.addresses=10.0.0.1:9200\n! goosefs.master.hostname=master-1\n"
+        ));
+        assert!(!site_properties_declare_master(
+            "goosefs.master.hostname=\n"
+        ));
+        assert!(!site_properties_declare_master(
+            "goosefs.master.rpc.addresses= , ,\n"
+        ));
+        // The SDK consults `addresses` first and never falls back to
+        // `hostname` once the key is present, so a blank list declares
+        // nothing here either.
+        assert!(!site_properties_declare_master(
+            "goosefs.master.rpc.addresses=\ngoosefs.master.hostname=master-1\n"
+        ));
+    }
 
     #[test]
     fn test_builder_build() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let builder = GoosefsBuilder::default()
             .root("/data")
             .master_addr("127.0.0.1:9200")
@@ -423,6 +747,7 @@ mod tests {
 
     #[test]
     fn test_builder_ha() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let builder = GoosefsBuilder::default()
             .root("/data")
             .master_addr("10.0.0.1:9200,10.0.0.2:9200,10.0.0.3:9200")
@@ -437,6 +762,7 @@ mod tests {
     /// before any auto-load value can rescue it.
     #[test]
     fn test_builder_blank_master_addr_fails() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let err = GoosefsBuilder::default()
             .root("/data")
             .master_addr("   ,  , ")
@@ -451,6 +777,7 @@ mod tests {
 
     #[test]
     fn test_capability_rename_with_if_not_exists() {
+        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let backend = GoosefsBuilder::default()
             .root("/data")
             .master_addr("127.0.0.1:9200")

data/core/services/goosefs/src/config.rs

@@ -46,12 +46,18 @@ pub struct GoosefsConfig {
     ///
     /// Resolution precedence at `build()` time (highest → lowest), following
     /// [goosefs-sdk `docs/CLIENT_CONFIGURATION.md`](https://github.com/Tencent/tencent-goosefs-rust-sdk/blob/main/docs/CLIENT_CONFIGURATION.md) §1:
-    ///   1. This field (when set on the builder / OpenDAL config map)
-    ///   2. `GOOSEFS_MASTER_ADDR` environment variable
-    ///   3. `goosefs.master.rpc.addresses` / `goosefs.master.hostname` in
+    ///   1. `GOOSEFS_MASTER_ADDR` environment variable
+    ///   2. `goosefs.master.rpc.addresses` / `goosefs.master.hostname` in
     ///      `goosefs-site.properties`
+    ///   3. This field (from the builder, the OpenDAL config map, or the URI
+    ///      authority of `goosefs://host:port/path`)
     ///
-    /// `build()` fails with `ConfigInvalid` only when **none** of the above
+    /// A site file that declares masters therefore outranks this field: the
+    /// file carries the deployment's whole HA master list, which a single URI
+    /// authority cannot express. Set `GOOSEFS_MASTER_ADDR` to override a
+    /// deployed site file for one process.
+    ///
+    /// `build()` fails with `ConfigInvalid` when **none** of the above
     /// supplies a master address.
     pub master_addr: Option<String>,
 
@@ -164,12 +170,14 @@ mod tests {
 
     /// HA note: since URIs don't allow commas in `host`, HA mode is
     /// expressed through the extra-option/env-var pathway, not through the
-    /// URI authority. When both are present the URI authority **wins** —
-    /// this is the deliberate contract of `from_uri` (it ensures a user who
-    /// typed `goosefs://host:port/` can't be silently overridden by a stale
-    /// env var). The full HA list therefore reaches `build()` only when the
-    /// caller goes through `from_iter` / `Operator::via_iter` without the
-    /// URI authority, which is covered by [`from_iter_picks_up_every_known_field`].
+    /// URI authority. When both are present the URI authority **wins** the
+    /// `master_addr` slot — a user who typed `goosefs://host:port/` must not
+    /// be silently redirected by a stale option map. The full HA list
+    /// therefore reaches `build()` only when the caller goes through
+    /// `from_iter` / `Operator::via_iter` without the URI authority, which is
+    /// covered by [`from_iter_picks_up_every_known_field`], or through
+    /// `goosefs-site.properties` / `GOOSEFS_MASTER_ADDR`, which outrank
+    /// `master_addr` inside `build()`.
     #[test]
     fn from_uri_authority_overrides_extra_master_addr() {
         let uri = OperatorUri::new(

data/core/services/goosefs/src/core.rs

@@ -19,12 +19,12 @@ use std::fmt::Debug;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicU32, Ordering};
 
+use asyncband::rwlock::RwLock;
 use goosefs_sdk::client::MasterClient;
 use goosefs_sdk::config::GoosefsConfig as ClientConfig;
 use goosefs_sdk::context::FileSystemContext;
 use goosefs_sdk::io::{GoosefsFileReader, GoosefsFileWriter};
 use goosefs_sdk::proto::grpc::file::FileInfo;
-use tokio::sync::RwLock;
 
 use opendal_core::raw::*;
 use opendal_core::*;

data/core/services/goosefs/src/docs.md

@@ -23,6 +23,8 @@ which means it connects directly to GooseFS Master (port 9200) and
 Worker (port 9203) without requiring a Proxy component.
 
 Features:
+- **Read metadata**: Streams expose full-file metadata from the SDK reader before
+  consuming the body. Bounded reads do not issue a separate stat to obtain it.
 - **HA support**: Comma-separated master addresses for automatic Primary Master discovery.
 - **Block-level I/O**: Data reads/writes go through block-level gRPC bidirectional streaming.
 - **Consistent hash routing**: Worker selection uses consistent hashing on block IDs.
@@ -32,6 +34,9 @@ Features:
 - **Rename parent directories**: `rename` creates a missing destination parent only
   when Master reports it missing. Write-via-temp publish does not call
   `CreateDirectory` for a parent that `CreateFile(recursive)` already created.
+- **Optional client caches**: `goosefs-sdk` 0.2.1 keeps metadata and page caches
+  behind Cargo features so the default build stays a gRPC client. Enable them
+  on this crate; see [Optional client caches](#optional-client-caches).
 
 ## Configuration
 
@@ -39,6 +44,71 @@ Use [`crate::GoosefsConfig`] for serializable configuration and this builder's
 methods for direct construction. The field and method documentation defines
 accepted values, defaults, and environment interaction.
 
+### Master address resolution
+
+`build()` resolves the master addresses from three sources, highest priority
+first:
+
+1. the `GOOSEFS_MASTER_ADDR` environment variable, either a comma-separated
+   list or the SDK's `gfs://h1:9200,h2:9200/root` URI form;
+2. `goosefs.master.rpc.addresses` or `goosefs.master.hostname` in
+   `goosefs-site.properties`, discovered through `$GOOSEFS_CONFIG_FILE`,
+   `$GOOSEFS_CONF_DIR`, `$GOOSEFS_HOME/conf`, `~/.goosefs`, and `/etc/goosefs`.
+   Use `$GOOSEFS_CONFIG_FILE` to point at a file outside those directories;
+3. the `master_addr` config key, which also receives the URI authority of
+   `goosefs://host:port/path`.
+
+A site file that declares masters outranks `master_addr` because the file
+carries a deployment's whole HA master list, which a single URI authority
+cannot express. Set `GOOSEFS_MASTER_ADDR` to override a deployed site file for
+one process. `build()` fails with `ConfigInvalid` when no source supplies an
+address; it never falls back to `127.0.0.1:9200`.
+
+| `goosefs-site.properties` | `GOOSEFS_MASTER_ADDR` | `master_addr` / URI authority | Master addresses used |
+| --- | --- | --- | --- |
+| declares masters | set | any | `GOOSEFS_MASTER_ADDR` |
+| declares masters | unset | any or absent | site file |
+| absent, or no master keys | set | any | `GOOSEFS_MASTER_ADDR` |
+| absent, or no master keys | unset | set | `master_addr` |
+| absent, or no master keys | unset | absent | none — `ConfigInvalid` |
+
+### Optional client caches
+
+`goosefs-sdk` 0.2.1 compiles the client metadata cache and the disk-backed page
+cache only when their Cargo features are enabled. The default
+`services-goosefs` / `opendal-service-goosefs` build stays a gRPC client.
+
+Enable a cache on this crate. Applications that use the `opendal` facade still
+add `opendal-service-goosefs` as a direct dependency so Cargo unifies the
+features into the same build:
+
+| Feature | Compiles |
+| --- | --- |
+| `metadata-cache` | Process-local status / listing LRU |
+| `page-cache` | Disk-backed page cache via `tokio::fs` |
+| `page-cache-io-uring` | Page cache plus the Linux io_uring backend |
+
+```shell
+cargo add opendal --features services-goosefs
+cargo add opendal-service-goosefs --features metadata-cache,page-cache-io-uring
+```
+
+`page-cache-io-uring` already enables `page-cache`. On non-Linux targets the
+SDK still builds the portable `tokio::fs` store; io_uring is Linux-only.
+
+Compiling a cache does not replace runtime configuration. `build()` loads
+`goosefs-site.properties` and `GOOSEFS_*` environment variables through
+`GoosefsConfig::from_properties_auto()`:
+
+- **Metadata cache**: on by default once `metadata-cache` is compiled. Set
+  `GOOSEFS_METADATA_CACHE_ENABLED=false` to disable it.
+- **Page cache**: off by default. Set `GOOSEFS_USER_CLIENT_CACHE_ENABLED=true`
+  and configure cache directories through
+  `goosefs.user.client.cache.dirs` / `GOOSEFS_USER_CLIENT_CACHE_DIRS`.
+
+See [goosefs-sdk client configuration](https://github.com/Tencent/tencent-goosefs-rust-sdk/blob/main/docs/CLIENT_CONFIGURATION.md)
+for the full cache knob list.
+
 ## Example
 
 ### Via Builder
@@ -140,8 +210,7 @@ This service is covered by all three OpenDAL test layers:
    `create_dir`). Start the fixture and point the harness at it:
 
    ```shell
-   # Start a single-container GooseFS (master + worker + job_master +
-   # job_worker + table_master)
+   # Start a single-container GooseFS (master + worker; see start-default.sh)
    docker compose -f fixtures/goosefs/docker-compose-goosefs.yml up -d --wait
 
    OPENDAL_TEST=goosefs \
@@ -158,7 +227,7 @@ This service is covered by all three OpenDAL test layers:
 3. **GitHub CI** — `.github/services/goosefs/goosefs/action.yml` is picked up
    automatically by `.github/scripts/test_behavior/plan.py::provided_cases()`
    and runs the fixture + behavior suite on every PR. The fixture image
-   (`goosefs.tencentcloudcr.com/goosefs/repo:v2.1.0`) is public so no secrets
+   (`ghcr.io/tencent/tencent-goosefs-rust-sdk/goosefs:v2.0.0`) is public so no secrets
    are needed.
 
 The fixture also exposes a `distributed` compose profile (separate master /