Struct GooseFs 

pub struct GooseFs { /* private fields */ }

Available on crate feature services-goosefs only.

GooseFS services support via native gRPC.

Capabilities

This service can be used to:

• create_dir
• stat
• read
• write
• delete
• list
• copy
• rename
• presign

Notes

GooseFS service uses native gRPC protocol (not REST API like Alluxio), which means it connects directly to GooseFS Master (port 9200) and Worker (port 9203) without requiring a Proxy component.

Features:

• 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.
• All WriteTypes: Supports MUST_CACHE, CACHE_THROUGH, THROUGH, and ASYNC_THROUGH.

Configuration

• root: Set the work directory for backend
• master_addr: GooseFS Master address (host:port), supports comma-separated for HA
• block_size: Block size for new files (default: 64 MiB)
• chunk_size: Chunk size for streaming RPCs (default: 1 MiB)
• write_type: Default write type (must_cache, cache_through, through, async_through)
• auth_type: Authentication type (nosasl, simple). Default: simple
• auth_username: Authentication username for SIMPLE mode. Default: current OS user

You can refer to GoosefsBuilder’s docs for more information

Example

Via Builder

use opendal::Operator;
use opendal::Result;
use opendal::services::GooseFs;

#[tokio::main]
async fn main() -> Result<()> {
    // Single master
    let builder = GooseFs::default()
        .root("/data")
        .master_addr("10.0.0.1:9200");

    let op: Operator = Operator::new(builder)?.finish();

    Ok(())
}

Via URI

use opendal::Operator;
use opendal::Result;

#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::from_uri("goosefs://10.0.0.1:9200/data")?;
    Ok(())
}

HA Mode

use opendal::Operator;
use opendal::Result;
use opendal::services::GooseFs;

#[tokio::main]
async fn main() -> Result<()> {
    let builder = GooseFs::default()
        .root("/data")
        .master_addr("10.0.0.1:9200,10.0.0.2:9200,10.0.0.3:9200")
        .write_type("cache_through");

    let op: Operator = Operator::new(builder)?.finish();

    Ok(())
}

With Authentication

use opendal::Operator;
use opendal::Result;
use opendal::services::GooseFs;

#[tokio::main]
async fn main() -> Result<()> {
    // SIMPLE authentication (default) with custom username
    let builder = GooseFs::default()
        .root("/data")
        .master_addr("10.0.0.1:9200")
        .auth_type("simple")
        .auth_username("myuser");

    let op: Operator = Operator::new(builder)?.finish();

    // No authentication (NOSASL mode)
    let builder = GooseFs::default()
        .root("/data")
        .master_addr("10.0.0.1:9200")
        .auth_type("nosasl");

    let op: Operator = Operator::new(builder)?.finish();

    Ok(())
}

Testing

This service is covered by all three OpenDAL test layers:

1. Unit tests (no cluster required) — exercise Config/Builder/error-mapping boundaries. Run:

   cargo test -p opendal-service-goosefs

2. Behavior tests (require a running GooseFS cluster) — the shared core/tests/behavior suite (read/write/list/stat/rename/delete/ create_dir). Start the fixture and point the harness at it:

   # Start a single-container GooseFS (master + worker + job_master +
   # job_worker + table_master)
   docker compose -f fixtures/goosefs/docker-compose-goosefs.yml up -d --wait
   
   OPENDAL_TEST=goosefs \
   OPENDAL_GOOSEFS_MASTER_ADDR=127.0.0.1:9200 \
   OPENDAL_GOOSEFS_ROOT=/ \
   cargo test behavior --features tests,services-goosefs
   
   docker compose -f fixtures/goosefs/docker-compose-goosefs.yml down

   If OPENDAL_TEST is unset the behavior suite automatically skips, so missing a cluster is safe.

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 are needed.

The fixture also exposes a distributed compose profile (separate master / worker / job_master / job_worker containers) for multi-node diagnostics; opt in via --profile distributed.

Implementations

impl GoosefsBuilder

pub fn root(self, root: &str) -> GoosefsBuilder

Set root of this backend.

All operations will happen under this root.

pub fn master_addr(self, addr: &str) -> GoosefsBuilder

Set master address(es).

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 §1. build() fails with ConfigInvalid only if no source supplies a master address.

pub fn block_size(self, size: u64) -> GoosefsBuilder

Set block size for new files (bytes).

pub fn chunk_size(self, size: u64) -> GoosefsBuilder

Set chunk size for streaming RPCs (bytes).

pub fn write_type(self, wt: &str) -> GoosefsBuilder

Set default write type.

Values: "must_cache", "cache_through", "through", "async_through"

pub fn auth_type(self, auth_type: &str) -> GoosefsBuilder

Set authentication type.

Values: "nosasl", "simple" (default: "simple").

• "nosasl" — skip SASL authentication entirely.
• "simple" — PLAIN SASL with username (server does not verify password).

pub fn auth_username(self, username: &str) -> GoosefsBuilder

Set authentication username.

Used in SIMPLE mode as the login identity. Default: current OS user ($USER / $USERNAME).

Trait Implementations

impl Builder for GoosefsBuilder

fn build(self) -> Result<impl Access, Error>

Build the backend and return a GoosefsBackend.

type Config = GoosefsConfig

Associated configuration for this builder.

impl Debug for GoosefsBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for GoosefsBuilder

fn default() -> GoosefsBuilder

Returns the “default value” for a type.